huff: Market Area Analysis in Python

The huff Python library is designed for performing market area analyses with the Huff Model (Huff 1962, 1963, 1964) and/or the Multiplicative Competitive Interaction (MCI) Model (Nakanishi and Cooper 1974, 1982), as well as market area and accessibility models derived from or related to them. The package is intended for researchers in economic geography, regional economics, marketing, geoinformation science, and health geography. It is designed to cover the entire workflow of a market area analysis, including model calibration and GIS-related processing.

Users may load point shapefiles (or CSV, XLSX) of customer origins and supply locations and conduct a market area analysis step by step. The first step after importing is always to create an interaction matrix with a built-in function, on the basis of which all implemented models can then be calculated. The library supports parameter estimation based on empirical customer data using the MCI Model, Maximum Likelihood estimation, or local optimization. See Huff and McCallum (2008), Orpana and Lampinen (2003) and Wieland (2017) for a description of the models, their practical application and fitting procedures. The library includes functions for accessibility analysis, which may be combined with market area analysis, namely the Hansen accessibility (Hansen 1959) and the Two-step floating catchment area analysis (Luo and Wang 2003, Luo 2014). Competitor accessibility/concentration may also be calculated directly in order to extend the Huff model in terms of the Competing Destinations Model (Fotheringham 1985).

The package also includes auxiliary GIS functions for market area and accessibility analysis (e.g., buffer, distance matrix, overlay statistics) and clients for OpenRouteService(1) for network analysis (e.g., transport cost matrix) and OpenStreetMap(2) for simple maps. All auxiliary functions are implemented in the market area analysis functions but are also able to be used stand-alone.

Author

Thomas Wieland ORCID EMail

Availability

• 📦 PyPI: huff
• 💻 GitHub Repository: huff_official
• 📄 DOI (Zenodo): 10.5281/zenodo.18639559

Documentation

• Software paper: arXiv
• Methodological overview: Handbook of Market Area and Accessibility Models

A brief discussion of the included models and their application in the huff package may also be found in an article available at Medium.

Citation

If you use this software, please cite:

Wieland, T. (2026). huff: Market Area Analysis in Python (Version 1.9.13) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.18639559

Installation

To install the current version of the package from the Python Package Index (PyPI), use pip:

pip install huff

To install the package from GitHub with pip:

pip install git+https://github.com/geowieland/huff_official.git

Features

• Data management and preliminary analysis:
  • Importing tables or point geodata or interaction matrix
  • Setting attributes of customer origins and supply locations (variables, weightings)
  • Creating interaction matrix from point geodata (origins and destinations), including calculation of transport costs (distance, travel time)
  • Creating interaction matrix from survey data
• Huff Model:
  • Basic Huff Model analysis based on an interaction matrix
  • Different function types: power, exponential, logistic
  • Defining further attraction indicators in the utility function
  • Extend Huff Model to Competing Destinations Model by calculating and including competitor concentration variables
  • Huff model parameter estimation via Maximum Likelihood (ML) by probalities, customer flows, and total market areas
  • Huff model fit via local optimization of attraction
  • Huff model market simulation
• Multiplicative Competitive Interaction Model:
  • Log-centering transformation of interaction matrix
  • Fitting MCI model with >= 2 independent variables in the utility function
  • Huff-like MCI model market simulation
  • MCI model market simulation with inverse log-centering transformation
• Machine Learning Based Market Area Models:
  • Fitting customer flows model with >= 2 independent variables in the utility function
  • Huff-like market simulation
• Hansen Accessibility:
  • Calculating basic Hansen accessibility based on an interaction matrix
  • Calculating multivariate and (empirically) weighted Hansen accessibility based on an interaction matrix
• Two-Step Floating Catchment Area (2SFCA) Analysis:
  • Calculating basic 2SFCA analysis based on an interaction matrix
  • Calculating multivariate and (empirically) weighted 2SFCA analysis based on an interaction matrix
• GIS tools:
  • OpenRouteService(1) Client (implemented in model functions, but also available stand-alone):
    • Creating transport costs matrix from origins and destinations
    • Creating isochrones from origins and destinations
  • OpenStreetMap(2) Client (implemented in model functions, but also available stand-alone):
    • Creating simple maps with OSM basemap
  • Other GIS tools (implemented in model functions, but also available stand-alone):
    • Creating buffers from geodata
    • Spatial join with with statistics
    • Creating euclidean distance matrix from origins and destinations
    • Overlay-difference analysis of polygons

(1) © openrouteservice.org by HeiGIT | Map data © OpenStreetMap contributors | https://openrouteservice.org/

(2) © OpenStreetMap contributors | available under the Open Database License | https://www.openstreetmap.org/

Examples

# Workflow for basic Huff model analysis:

from huff.data_management import load_geodata
from huff.models import create_interaction_matrix

Haslach = load_geodata(
    "data/Haslach.shp",
    location_type="origins",
    unique_id="BEZEICHN"
    )
# Loading customer origins (shapefile)

Haslach.define_marketsize("pop")
# Definition of market size variable

Haslach.define_transportcosts_weighting(
    func = "power",
    param_lambda = -2.2,    
    )
# Definition of transport costs weighting (lambda)

Haslach.summary()
# Summary after update

Haslach_supermarkets = load_geodata(
    "data/Haslach_supermarkets.shp",
    location_type="destinations",
    unique_id="LFDNR"
    )
# Loading supply locations (shapefile)

Haslach_supermarkets.define_attraction("VKF_qm")
# Defining attraction variable

Haslach_supermarkets.define_attraction_weighting(
    param_gamma=0.9
    )
# Define attraction weighting (gamma)

Haslach_supermarkets.summary()
# Summary of updated customer origins

haslach_interactionmatrix = create_interaction_matrix(
    Haslach,
    Haslach_supermarkets
    )
# Creating interaction matrix

haslach_interactionmatrix.transport_costs(
    ors_auth="<<Your ORS API key>>",
    # Get your ORS API key at: https://account.heigit.org/signup
    network=True,
    )
# Obtaining transport costs (default: driving-car)
# set network = True to calculate transport costs matrix via ORS API (default)
# ORS API documentation: https://openrouteservice.org/dev/#/api-docs/v2/

haslach_interactionmatrix.summary()
# Summary of interaction matrix

haslach_interactionmatrix.flows()
# Calculating spatial flows for interaction matrix

huff_model = haslach_interactionmatrix.marketareas()
# Calculating total market areas
# Result of class HuffModel

huff_model.summary()
# Summary of Huff model

haslach_interactionmatrix.plot(
    origin_point_style = {
        "name": "Districts",
        "color": "black",
        "alpha": 1,
        "size": 100,
        },
    location_point_style = {
        "name": "Supermarket chains",
        "color": {
            "Name": {
                "Aldi Süd": "blue",
                "Edeka": "yellow",
                "Lidl": "red",
                "Netto": "orange",
                "Real": "darkblue",
                "Treff 3000": "fuchsia"
                }
            },
        "alpha": 1,
        "size": 100
        },    
    )
# Plot of interaction matrix with expected customer flows

For detailed examples, see the /examples folder in the public GitHub repository.

Literature

• Benoit D, Clarke GP (1997) Assessing GIS for retail location planning. Journal of Retailing and Consumer Services 4(4): 239-258. 10.1016/S0969-6989(96)00047-1
• Cooper LG, Nakanishi M (1983) Standardizing Variables in Multiplicative Choice Models. Journal of Consumer Research 10(1): 96–108. 10.1086/208948
• De Beule M, Van den Poel D, Van de Weghe N (2014) An extended Huff-model for robustly benchmarking and predicting retail network performance. Applied Geography 46(1): 80–89. 10.1016/j.apgeog.2013.09.026
• Fotheringham AS (1985) Spatial Competition and Agglomeration in Urban Modelling. Environment and Planning A: Economy and Space 17(2): 213-230. 10.1068/a170213
• Güssefeldt J (2002) Zur Modellierung von räumlichen Kaufkraftströmen in unvollkommenen Märkten. Erdkunde 56(4): 351–370. 10.3112/erdkunde.2002.04.02
• Haines Jr GH, Simon LS, Alexis M (1972) Maximum Likelihood Estimation of Central-City Food Trading Areas. Journal of Marketing Research 9(2): 154-159. 10.2307/3149948
• Hansen WG (1959) How Accessibility Shapes Land Use. Journal of the American Institute of Planners 25(2): 73-76. 10.1080/01944365908978307
• Huff DL (1962) Determination of Intra-Urban Retail Trade Areas. Real Estate Research Program, Graduate Schools of Business Administration, University of California.
• Huff DL (1963) A Probabilistic Analysis of Shopping Center Trade Areas. Land Economics 39(1): 81-90. 10.2307/3144521
• Huff DL (1964) Defining and estimating a trading area. Journal of Marketing 28(4): 34–38. 10.2307/1249154
• Huff DL (2003) Parameter Estimation in the Huff Model. ArcUser 6(4): 34–36. https://stg.esri.com/news/arcuser/1003/files/huff.pdf
• Huff DL, Batsell RR (1975) Conceptual and Operational Problems with Market Share Models of Consumer Spatial Behavior. Advances in Consumer Research 2(1): 165-172.
• Huff DL, McCallum BM (2008) Calibrating the Huff Model using ArcGIS Business Analyst. ESRI White Paper, September 2008. https://www.esri.com/library/whitepapers/pdfs/calibrating-huff-model.pdf.
• Luo W, Wang F (2003) Measures of spatial accessibility to health care in a GIS environment: synthesis and a case study in the Chicago region. Environment and Planning B: Planning and Design 30: 865-884. 10.1068/b29120
• Luo J (2014) Integrating the Huff Model and Floating Catchment Area Methods to Analyze Spatial Access to Healthcare Services. Transactions in GIS 18(3): 436-448. 10.1111/tgis.12096
• Miller H, Shaw SL (2015) Geographic Information Systems for Transportation in the 21st Century. Geography Compass 9(4): 180-189. 10.1111/gec3.12204
• Nakanishi M, Cooper LG (1974) Parameter estimation for a Multiplicative Competitive Interaction Model: Least squares approach. Journal of Marketing Research 11(3): 303–311. 10.2307/3151146.
• Nakanishi M, Cooper LG (1982) Technical Note — Simplified Estimation Procedures for MCI Models. Marketing Science 1(3): 314-322. 10.1287/mksc.1.3.314
• Orpana T, Lampinen J (2003) Building Spatial Choice Models from Aggregate Data. Journal of Regional Science 43(2): 319-348. 10.1111/1467-9787.00301
• Rauch S, Wieland T, Rauh J (2025) Accessibility of food - A multilevel approach comparing a choice based model with perceived accessibility in Mainfranken, Germany. Journal of Transport Geography 128: 104367. 10.1016/j.jtrangeo.2025.104367
• Wieland T (2015) Räumliches Einkaufsverhalten und Standortpolitik im Einzelhandel unter Berücksichtigung von Agglomerationseffekten - Theoretische Erklärungsansätze, modellanalytische Zugänge und eine empirisch-ökonometrische Marktgebietsanalyse anhand eines Fallbeispiels aus dem ländlichen Raum Ostwestfalens/Südniedersachsens. Mannheim: MetaGIS. https://nbn-resolving.org/urn:nbn:de:bvb:20-opus-180753
• Wieland T (2017) Market Area Analysis for Retail and Service Locations with MCI. R Journal 9(1): 298-323. 10.32614/RJ-2017-020
• Wieland T (2018) A Hurdle Model Approach of Store Choice and Market Area Analysis in Grocery Retailing. Papers in Applied Geography 4(4): 370-389. 10.1080/23754931.2018.1519458
• Wieland T (2018) Competitive locations of grocery stores in the local supply context - The case of the urban district Freiburg-Haslach. European Journal of Geography 9(3): 98-115. https://www.eurogeojournal.eu/index.php/egj/article/view/41

AI Usage Statement

This software was developed without the use of AI-generated code. GitHub Copilot in Microsoft Visual Studio Code using the GPT-5 mini model (by OpenAI) was used to assist in drafting and refining docstrings for documentation. The corresponding guidelines and constraints defined by the author are documented in AGENTS-docstrings.md in the public GitHub repository.

What's new (v1.9.13)

• Bugfixes:
  • goodness_of_fit.modelfit(): No (failing) R-squared calculation when total sum of squares is zero (additional NOTE message)
  • More detailed checks of input GeoDataFrame(s) in gistools functions buffers(), distance_matrix_from_gdf(), polygon_select(), point_spatial_join(), map_with_basemap(), and overlay_difference()
  • Corrections in documentation/README
• Other:
  • Extension of huff.info(): Displaying available models etc. and test for OSM and ORS server response