Market endpoints
City market overview, category rankings, brand performance across cities and county migration.
Market endpoints aggregate foot traffic across a city, a category or a brand, plus county migration for the US metros. They require authentication, count as ordinary API calls (not analyses) and follow the date-range rules (except migration, which has a single period). Paths are relative to https://api.mapdove.com/api/v1. For interpretation see Market intelligence.
| Method | Path | Purpose |
|---|---|---|
| GET | /market/:city/overview |
City totals, categories, weekly trend, movers, neighborhoods |
| GET | /rankings |
Places in a category ordered by visits |
| GET | /brands/:slug/performance |
A brand across all cities |
| GET | /market/:city/migration |
Where people moving into or out of the city’s metro come from or go (US cities) |
Market overview
GET /market/:city/overview
| Param | Description |
|---|---|
city |
path, city slug |
from, to |
date range |
curl "https://api.mapdove.com/api/v1/market/houston/overview?from=2026-08-01&to=2026-10-31" \
-H "Authorization: Bearer $MAPDOVE_KEY"
const ov = await fetch('https://api.mapdove.com/api/v1/market/houston/overview', {
headers: { Authorization: `Bearer ${key}` },
}).then((r) => r.json());
const growing = ov.by_category.filter((c) => c.change_pct > 0).map((c) => c.slug);
ov = requests.get(f"{BASE}/market/houston/overview", headers=H, timeout=60).json()
for c in sorted(ov["by_category"], key=lambda c: -c["share"])[:3]:
print(c["name"], round(c["share"] * 100, 1), "%", c["change_pct"])
{
"range": { "from": "2026-08-01", "to": "2026-10-31" },
"totals": { "visits": 12804412, "visits_prev": 12610038, "change_pct": 1.5 },
"by_category": [
{ "slug": "mall", "name": "Shopping Centers", "color": "#475569", "visits": 3521900, "change_pct": 2.4, "share": 0.275 },
{ "slug": "grocery", "name": "Grocery", "color": "#16a34a", "visits": 3110240, "change_pct": 0.9, "share": 0.243 }
],
"trend": [
{ "date": "2026-08-03", "visits": 968210 },
{ "date": "2026-08-10", "visits": 975402 }
],
"top_movers": {
"up": [ { "id": 402, "name": "Midtown Burger Joint", "change_pct": 18.2, "…": "…" } ],
"down": [ { "id": 455, "name": "Crispy Coop · Gulfton", "change_pct": -9.7, "…": "…" } ]
},
"by_neighborhood": [
{ "name": "Uptown Galleria", "visits": 1490330, "change_pct": 1.8 },
{ "name": "Downtown", "visits": 1201876, "change_pct": 0.6 }
]
}
shareis the category’s fraction of total city visits in the range.trendis weekly;top_movers.upand.downhold fivePlaceSummaryobjects each, ranked bychange_pct.
Rankings
GET /rankings — all places of a category in a city, ordered by visits, with rank_in_category.
| Param | Description |
|---|---|
city |
required city slug |
category |
required category slug |
from, to |
date range |
limit |
default 50, max 500 |
curl "https://api.mapdove.com/api/v1/rankings?city=dubai&category=mall&limit=3" \
-H "Authorization: Bearer $MAPDOVE_KEY"
top = requests.get(f"{BASE}/rankings", headers=H,
params={"city": "dubai", "category": "mall", "limit": 3}, timeout=30).json()
[
{ "id": 1201, "name": "Downtown Dubai Galleria", "rank_in_category": 1, "visits": 1184210, "change_pct": 6.1, "avg_daily_visits": 12872, "…": "…" },
{ "id": 1219, "name": "Dubai Marina Town Center", "rank_in_category": 2, "visits": 1012944, "change_pct": 4.8, "avg_daily_visits": 11010, "…": "…" },
{ "id": 1224, "name": "Deira Plaza", "rank_in_category": 3, "visits": 820531, "change_pct": 3.9, "avg_daily_visits": 8919, "…": "…" }
]
Each item is a full PlaceSummary.
Brand performance
GET /brands/:slug/performance — one brand across every city where it operates.
| Param | Description |
|---|---|
slug |
path, brand slug (see GET /brands) |
from, to |
date range |
curl "https://api.mapdove.com/api/v1/brands/bean-republic/performance" \
-H "Authorization: Bearer $MAPDOVE_KEY"
const perf = await fetch('https://api.mapdove.com/api/v1/brands/bean-republic/performance', {
headers: { Authorization: `Bearer ${key}` },
}).then((r) => r.json());
const best = [...perf.by_city].sort((a, b) => b.avg_per_location - a.avg_per_location)[0];
perf = requests.get(f"{BASE}/brands/bean-republic/performance", headers=H, timeout=60).json()
print({s["city"]: s["share"] for s in perf["market_share"]})
{
"brand": { "id": 1, "slug": "bean-republic", "name": "Bean Republic", "category": "coffee", "color": "#6f4e37", "price_tier": 2, "locations": 40 },
"by_city": [
{ "city": "austin", "name": "Austin", "locations": 9, "visits": 318402, "avg_per_location": 35378, "change_pct": 3.2 },
{ "city": "miami", "name": "Miami", "locations": 7, "visits": 241866, "avg_per_location": 34552, "change_pct": 5.0 }
],
"trend": [ { "date": "2026-08-03", "visits": 101233 } ],
"locations": [ { "id": 42, "name": "Bean Republic · Downtown", "…": "…" } ],
"market_share": [ { "city": "austin", "share": 0.312 }, { "city": "miami", "share": 0.287 } ]
}
avg_per_location= visits ÷ locations in the range.trendis weekly across all locations.market_shareis the brand’s share of its category’s visits in each city.
County migration
GET /market/:city/migration — moves into and out of the counties of the city’s metropolitan area, from the US Census Bureau’s ACS county-to-county migration flows. It doesn’t take a date range: the data is one 5-year period (2016–2020, the latest county-to-county release).
| Param | Description |
|---|---|
city |
path, city slug |
direction |
in (default: where movers into the metro came from) or out (where movers out of it went) |
limit |
top counties to return, default 15, max 50 |
curl "https://api.mapdove.com/api/v1/market/austin/migration?direction=in&limit=5" \
-H "Authorization: Bearer $MAPDOVE_KEY"
mig = requests.get(f"{BASE}/market/austin/migration", headers=H,
params={"direction": "in", "limit": 5}, timeout=30).json()
if mig["available"]:
for c in mig["top_counties"]:
print(c["name"], c["state"], c["flow"]["estimate"], "±", c["flow"]["moe"])
{
"available": true,
"city": "austin",
"source": { "kind": "acs", "period": "2016–2020", "start_year": 2016, "end_year": 2020 },
"metro": { "code": "12420", "name": "Austin-Round Rock-San Marcos, TX", "counties": 5 },
"direction": "in",
"totals": {
"population": { "estimate": 2149925, "moe": 1207 },
"moved_in": { "estimate": 128374, "moe": 5232 },
"moved_out": { "estimate": 97226, "moe": 3875 },
"net": { "estimate": 31148, "moe": 6428 },
"from_abroad": { "estimate": 16654, "moe": 1641 }
},
"counties": [
{ "geoid": "48491", "name": "Williamson County", "state": "TX", "population": { "estimate": 564232, "moe": 663 },
"moved_in": { "estimate": 51528, "moe": 3796 }, "moved_out": { "estimate": 32996, "moe": 2389 },
"net": { "estimate": 18532, "moe": 4485 }, "net_per_1000": 32.8, "from_abroad": { "estimate": 4355, "moe": 886 }, "lng": -97.5985, "lat": 30.6467 }
],
"top_counties": [
{ "geoid": "48201", "name": "Harris County", "state": "TX", "flow": { "estimate": 10008, "moe": 1150 },
"counterflow": { "estimate": 6245, "moe": 968 }, "net": { "estimate": 3763, "moe": 1561 }, "share": 0.078, "lng": -95.3947, "lat": 29.8589 }
],
"top_states": [ { "code": "48", "abbr": "TX", "name": "Texas", "flow": { "estimate": 64572, "moe": 3438 }, "net": { "estimate": 10305, "moe": 4554 }, "share": 0.503 } ],
"abroad": [ { "code": "ASI", "name": "Asia", "flow": { "estimate": 6572, "moe": 1096 }, "share": 0.3946 } ],
"map": { "counties": { "type": "FeatureCollection", "features": [] }, "flows": { "type": "FeatureCollection", "features": [] } }
}
- Every figure is
{ estimate, moe }: a survey estimate and its margin of error at 90 % confidence. Sums of published figures use the Census Bureau’s approximation √(Σ MOE²). totalsdescribe the metro as a whole (moves between its own counties don’t count);countiescount every move from or to another US county.flowis in the requested direction,counterflowthe opposite one,net= into the metro − out of it.abroadis empty forout: the ACS doesn’t measure moves out of the country.map.countiesholds the metro’s county polygons (propertiesgeoid,name,net,net_per_1000) andmap.flowsone line per top county between it and the city’s centre, in the direction of the move.source.kindisacsfor the Census data andsyntheticon installations that run on the demo baseline. Dubai answers{ "available": false, "reason": "not_available_for_city" }; a US city whose installation hasn’t loaded the data answers"reason": "not_loaded".- Errors:
400for adirectionother thaninorout,404for an unknown city.
Names and figures in the examples are illustrative, except the migration example, which shows the first item of each list of the real 2016–2020 answer for Austin (lists shortened). Brand visits are modeled estimates; migration figures are survey estimates (Data sources).