SDSS endpoints — Documentation

Run site suitability, Huff visit forecasts with cannibalization, catchment rings and multi-site comparisons through the API.

The spatial decision support endpoints run MapDove’s models on demand. They are POST endpoints with JSON bodies, require authentication and are relative to https://api.mapdove.com/api/v1.

Each successful call counts one analysis toward your monthly plan allowance (Free 25, Pro 500, Business and Enterprise unlimited), in addition to the API call. When the allowance is used up, calls return 402 plan_limit. Validation errors (400) do not consume an analysis.

Method	Path	Purpose
POST	`/sdss/suitability`	Weighted multi-criteria score for every hex, plus top sites
POST	`/sdss/huff`	Visit forecast and cannibalization for a candidate
POST	`/sdss/catchment`	Demographics in up to four rings
POST	`/sdss/compare-sites`	Score, forecast and catchment for up to five sites

Model details: Methodology.

Weights

Suitability and compare-sites take a Weights object. Every key is optional, each value is a number from 0 to 10, missing keys count as 0, and at least one weight must be positive. Unknown keys return 400.

{
  "population": 5, "income": 3, "daytime": 8, "traffic": 6, "growth": 2,
  "competition": 6, "complementary": 4, "rent": 3, "gap": 7
}

competition and rent are inverted criteria — a positive weight rewards less competition and lower rent. See Site suitability.

Suitability

POST /sdss/suitability

Field	Type	Description
`city`	string	required city slug
`category`	string	required category slug
`weights`	Weights	required
`top_n`	integer	1–50, default 10
`min_spacing_km`	number	0–50, default 1.5

curl -X POST https://api.mapdove.com/api/v1/sdss/suitability \
  -H "Authorization: Bearer $MAPDOVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "city": "austin",
    "category": "coffee",
    "weights": { "daytime": 8, "population": 5, "traffic": 6, "competition": 6, "gap": 7 },
    "top_n": 5,
    "min_spacing_km": 1.5
  }'

const res = await fetch('https://api.mapdove.com/api/v1/sdss/suitability', {
  method: 'POST',
  headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    city: 'austin',
    category: 'coffee',
    weights: { daytime: 8, population: 5, traffic: 6, competition: 6, gap: 7 },
    top_n: 5,
  }),
});
const { top_sites, stats } = await res.json();

body = {
    "city": "austin",
    "category": "coffee",
    "weights": {"daytime": 8, "population": 5, "traffic": 6, "competition": 6, "gap": 7},
    "top_n": 5,
}
r = requests.post(f"{BASE}/sdss/suitability", headers=H, json=body, timeout=120)
r.raise_for_status()
for s in r.json()["top_sites"]:
    print(s["rank"], s["neighborhood"], s["score"])

Response (trimmed):

{
  "geojson": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": { "type": "Polygon", "coordinates": ["…"] },
        "properties": {
          "hex_id": 77, "score": 72.4, "neighborhood": "Mueller",
          "population": 0.612, "income": 0.544, "daytime": 0.701, "traffic": 0.655, "growth": 0.833,
          "competition": 0.719, "complementary": 0.402, "rent": 0.488, "gap": 0.391
        }
      }
    ]
  },
  "top_sites": [
    {
      "rank": 1, "hex_id": 77, "score": 72.4, "lng": -97.7046, "lat": 30.2981, "neighborhood": "Mueller",
      "criteria": {
        "population": 0.612, "income": 0.544, "daytime": 0.701, "traffic": 0.655, "growth": 0.833,
        "competition": 0.719, "complementary": 0.402, "rent": 0.488, "gap": 0.391, "competitors_nearby": 1.84
      }
    },
    { "rank": 2, "hex_id": 431, "score": 70.9, "lng": -97.7232, "lat": 30.3998, "neighborhood": "The Domain", "criteria": { "…": "…" } }
  ],
  "stats": { "min": 11.8, "max": 72.4, "mean": 41.3 }
}

Criteria values are normalized 0–1 (already inverted for competition and rent). competitors_nearby is the raw distance-weighted competitor count.

Huff

POST /sdss/huff

Field	Type	Description
`city`	string	required
`category`	string	required
`lng`, `lat`	number	required; must be inside the city’s study area
`sqft`	number	100–2,000,000; default = category typical size
`brand_strength`	number	0.6–1.5; default 1.0

curl -X POST https://api.mapdove.com/api/v1/sdss/huff \
  -H "Authorization: Bearer $MAPDOVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "city": "austin", "category": "coffee", "lng": -97.7046, "lat": 30.2981, "sqft": 2200, "brand_strength": 1.1 }'

const huff = await fetch('https://api.mapdove.com/api/v1/sdss/huff', {
  method: 'POST',
  headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ city: 'austin', category: 'coffee', lng: -97.7046, lat: 30.2981, sqft: 2200, brand_strength: 1.1 }),
}).then((r) => r.json());
console.log(huff.predicted_daily_visits, huff.total_cannibalized_daily);

huff = requests.post(f"{BASE}/sdss/huff", headers=H, timeout=120, json={
    "city": "austin", "category": "coffee", "lng": -97.7046, "lat": 30.2981,
    "sqft": 2200, "brand_strength": 1.1,
}).json()

Response (trimmed):

{
  "attractiveness": 1.26,
  "calibration_k": 0.013812,
  "predicted_daily_visits": 397,
  "predicted_annual_visits": 145002,
  "market_share": 0.0338,
  "category_avg_daily_visits": 345,
  "total_cannibalized_daily": 212,
  "impacted": [
    {
      "place_id": 88, "name": "Bean Republic · Mueller", "lng": -97.6998, "lat": 30.2950,
      "distance_km": 0.6, "current_daily_visits": 412, "delta_daily_visits": -58, "delta_pct": -14.08
    }
  ],
  "trade_area": {
    "type": "FeatureCollection",
    "features": [
      { "type": "Feature", "geometry": { "type": "Polygon", "coordinates": ["…"] }, "properties": { "hex_id": 77, "share": 0.07311 } }
    ]
  }
}

impacted lists up to ten stores with the largest losses. trade_area covers the first 80% of the candidate’s modeled visitors. See Huff forecast and Cannibalization.

Catchment

POST /sdss/catchment

Field	Type	Description
`lng`, `lat`	number	required
`rings`	number[]	required, 1–4 positive values; each radius ≤ 50 km after conversion
`unit`	string	`km`, `mi` or `min`

min converts minutes to a radius with the average driving speed of the city containing the point — a radius approximation, not a road-network isochrone (Catchments).

curl -X POST https://api.mapdove.com/api/v1/sdss/catchment \
  -H "Authorization: Bearer $MAPDOVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "lng": -97.7046, "lat": 30.2981, "rings": [1, 3], "unit": "mi" }'

rings = requests.post(f"{BASE}/sdss/catchment", headers=H, timeout=60, json={
    "lng": -97.7046, "lat": 30.2981, "rings": [5, 10, 15], "unit": "min",
}).json()["rings"]
for r in rings:
    print(r["label"], r["radius_km"], r["population"])

Response (trimmed to one ring):

{
  "rings": [
    {
      "label": "1 mi", "radius_km": 1.609344, "area_km2": 8.14,
      "population": 18412, "households": 8120, "daytime_pop": 21904,
      "median_income": 104300, "median_age": 34.8, "pct_college": 49.6, "pct_family": 33.1,
      "traffic_index": 51.2, "rent_index": 58.7, "growth_rate": 0.0471,
      "segments": [
        { "slug": "urban-professionals", "name": "Urban Professionals", "color": "#14b8a6", "population": 9021, "share": 0.49 },
        { "slug": "suburban-families", "name": "Suburban Families", "color": "#22c55e", "population": 4234, "share": 0.23 }
      ],
      "places_by_category": [
        { "slug": "coffee", "name": "Coffee & Cafés", "color": "#92400e", "count": 4 },
        { "slug": "qsr", "name": "Quick Service", "color": "#dc2626", "count": 3 }
      ],
      "geometry": { "type": "Polygon", "coordinates": ["…"] }
    }
  ]
}

Compare sites

POST /sdss/compare-sites

Field	Type	Description
`city`	string	required
`category`	string	required
`sites`	`{ label, lng, lat }[]`	required, 1–5 sites
`weights`	Weights	suitability weights

The whole comparison counts as one analysis. Each site’s Huff forecast uses the category’s typical size and brand strength 1.0, and omits trade_area. catchment_1 is a 1-mile ring in US cities and a 1.6 km ring in Dubai.

curl -X POST https://api.mapdove.com/api/v1/sdss/compare-sites \
  -H "Authorization: Bearer $MAPDOVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "city": "austin",
    "category": "coffee",
    "sites": [
      { "label": "Mueller", "lng": -97.7046, "lat": 30.2981 },
      { "label": "The Domain", "lng": -97.7232, "lat": 30.3998 }
    ],
    "weights": { "daytime": 8, "population": 5, "traffic": 6, "competition": 6, "gap": 7 }
  }'

const cmp = await fetch('https://api.mapdove.com/api/v1/sdss/compare-sites', {
  method: 'POST',
  headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ city: 'austin', category: 'coffee', sites, weights }),
}).then((r) => r.json());
console.table(cmp.sites.map((s) => ({ site: s.label, score: s.score, visits: s.huff.predicted_daily_visits })));

Response (trimmed to one site):

{
  "sites": [
    {
      "label": "Mueller", "lng": -97.7046, "lat": 30.2981,
      "score": 72.4,
      "criteria": { "population": 0.612, "daytime": 0.701, "competition": 0.719, "gap": 0.391, "…": "…" },
      "huff": {
        "attractiveness": 1.0, "calibration_k": 0.013812, "predicted_daily_visits": 352,
        "predicted_annual_visits": 128480, "market_share": 0.0302, "category_avg_daily_visits": 345,
        "total_cannibalized_daily": 188, "impacted": [ { "place_id": 88, "delta_daily_visits": -51, "…": "…" } ]
      },
      "catchment_1": { "label": "1 mi", "radius_km": 1.609344, "population": 18412, "…": "…" }
    }
  ]
}

score and criteria come from the hex containing (or nearest to) the site; they are null if the point is not near any hex of the city grid.

Errors specific to SDSS

Status	`code`	Typical cause
400	`bad_request`	Unknown criterion; weight outside 0–10; all weights zero; point outside the study area; `sqft` or `brand_strength` out of range; more than 4 rings or 5 sites; ring over 50 km; bad `unit`
402	`plan_limit`	Monthly analyses used up
404	`not_found`	Unknown city or category slug