SDSS endpoints
Run site suitability, Huff visit forecasts with cannibalization, catchment rings, multi-site comparisons and drawn-area analysis 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 |
| POST | /sdss/area |
Demographics, places and modeled visits inside a polygon you draw |
| POST | /sdss/tenant-gaps |
Brands and categories missing around a place or point, ranked by modeled fit |
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.
Area analysis
POST /sdss/area
| Field | Type | Description |
|---|---|---|
city |
string | required |
geometry |
GeoJSON Polygon | required, one closed ring (no holes), at most 500 vertices, no self-intersections, at most 500 km², must overlap the city |
from, to |
string | optional YYYY-MM-DD, like every date range (default: the last 90 days) |
Demographics are weighted by the share of each hex cell inside the polygon, like catchment rings. Places and visits cover the places whose point lies inside. A polygon that breaks a rule returns 400 with a message that says which, and doesn’t use an analysis.
curl -X POST https://api.mapdove.com/api/v1/sdss/area \
-H "Authorization: Bearer $MAPDOVE_KEY" \
-H "Content-Type: application/json" \
-d '{ "city": "austin", "geometry": { "type": "Polygon", "coordinates": [[[-97.755, 30.255], [-97.732, 30.255], [-97.732, 30.275], [-97.755, 30.275], [-97.755, 30.255]]] } }'
Response (trimmed):
{
"city": "austin", "range": { "from": "2026-08-03", "to": "2026-10-31" },
"geometry": { "type": "Polygon", "coordinates": ["…"] }, "area_km2": 4.87,
"demographics": {
"hexes": 14, "population": 13657, "households": 5457, "daytime_pop": 35105,
"median_income": 102390, "median_age": 33.7, "pct_college": 48.3, "pct_family": 31.7,
"traffic_index": 73.8, "rent_index": 83.2, "growth_rate": 0.029,
"segments": [{ "slug": "urban-professionals", "name": "Urban Professionals", "color": "#14b8a6", "population": 6667, "share": 0.4882 }]
},
"places_by_category": [{ "slug": "coffee", "name": "Coffee & Cafés", "color": "#92400e", "count": 3 }],
"places_total": 22,
"visits": { "total": 1474495, "prev": 1582010, "change_pct": -6.8, "avg_daily": 16383,
"trend": [{ "date": "2026-08-03", "visits": 118204 }] },
"top_places": [{ "id": 261, "name": "Downtown Food Hall", "visits": 175458, "change_pct": -6.3, "…": "…" }]
}
visits are modeled estimates for the places inside; trend holds the full weeks inside the range, and top_places are the ten busiest places as place summaries. Save a drawn area as a project with kind: "area", params: { geometry, from, to } and the response as result.
Tenant gaps
POST /sdss/tenant-gaps
| Field | Type | Description |
|---|---|---|
place_id |
number | an existing place (or send city, lng, lat instead, not both) |
city |
string | required with lng/lat; optional with place_id (must be the place’s city) |
lng, lat |
number | a point inside the city’s study area |
radius |
number | area size; default 2 mi in US cities, 3 km in Dubai, 0.25–15 km |
unit |
"km" | "mi" | "min" |
min = drive minutes at the city’s average speed |
limit |
number | brands to return, default 20, at most 100 |
Every score in the response is a modeled indicator computed from MapDove’s own data, not a measurement.
brands: brands with no location inside the area.fit(0–100) compares the area’s demographics (income relative to the city, age, education, family share, daytime population, density, lifestyle segments) with the trade areas of the brand’s existing locations in every city;matchbreaks it down by factor (0–1).nearestis the brand’s closest location,cannibalization_risk(0–1) rises as it gets closer, andcompetitorscounts same-category places inside the area.scoreis the fit reduced for cannibalization risk and for more competitors than comparable areas carry.categories: every category, withactualplaces in the area againstexpected(from the 50 most similar areas elsewhere in the dataset),gap, and an under-supplyscore(0–100).top_brandsare the best brand candidates in each category.areais the radius’s catchment (as/sdss/catchment) andplaceslists up to 300 places inside it.
curl -X POST https://api.mapdove.com/api/v1/sdss/tenant-gaps \
-H "Authorization: Bearer $MAPDOVE_KEY" \
-H "Content-Type: application/json" \
-d '{ "city": "austin", "lng": -97.74, "lat": 30.27, "radius": 2, "unit": "mi", "limit": 10 }'
Response (trimmed):
{
"center": { "city": "austin", "lng": -97.74, "lat": 30.27, "place": null },
"radius_km": 3.219, "label": "2 mi",
"brands": [
{ "rank": 1, "brand": { "slug": "wellpoint", "name": "WellPoint Pharmacy", "…": "…" },
"score": 79.3, "fit": 83.8, "match": { "income": 0.92, "segments": 0.71, "…": "…" },
"locations": 26, "cities": 5,
"nearest": { "place_id": 311, "city": "austin", "distance_km": 5.44, "…": "…" },
"cannibalization_risk": 0.108, "competitors": 2 }
],
"categories": [
{ "rank": 1, "category": { "slug": "home", "…": "…" }, "actual": 0, "expected": 1.8, "gap": 1.8,
"supply_index": 0, "score": 64.4, "top_brands": [{ "slug": "buildright", "name": "BuildRight" }] }
],
"places_total": 70,
"model": { "comparables": 50, "brands_considered": 5, "brands_present": 26 }
}
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; area polygon not a single valid ring, over 500 vertices or 500 km², or outside the city; tenant-gap radius outside 0.25–15 km, or both/neither of place_id and lng/lat |
| 402 | plan_limit |
Monthly analyses used up |
| 404 | not_found |
Unknown city or category slug; unknown place_id |