Esta página aún no está traducida. Estás leyendo la versión en inglés.

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 }
  ]
}
  • share is the category’s fraction of total city visits in the range.
  • trend is weekly; top_movers.up and .down hold five PlaceSummary objects each, ranked by change_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.
  • trend is weekly across all locations.
  • market_share is 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²).
  • totals describe the metro as a whole (moves between its own counties don’t count); counties count every move from or to another US county.
  • flow is in the requested direction, counterflow the opposite one, net = into the metro − out of it. abroad is empty for out: the ACS doesn’t measure moves out of the country.
  • map.counties holds the metro’s county polygons (properties geoid, name, net, net_per_1000) and map.flows one line per top county between it and the city’s centre, in the direction of the move.
  • source.kind is acs for the Census data and synthetic on 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: 400 for a direction other than in or out, 404 for 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).