تسجيل الدخول ابدأ مجانًا

هذه الصفحة غير مترجمة بعد. أنت تقرأ النسخة الإنجليزية.

Reference data endpoints

Health, public stats, plans, cities, hex grids, neighborhoods, categories, brands and lifestyle segments.

Reference data describes the markets and taxonomies everything else refers to. It changes rarely, so cache it on your side (hours to days) and save API calls. Paths are relative to https://api.mapdove.com/api/v1 unless noted. Conventions, auth and errors are in the API overview.

Method Path Auth
GET /health (root, also /healthz) none
GET /public/stats none
GET /plans none
GET /cities required
GET /cities/:slug required
GET /cities/:slug/hexes required
GET /cities/:slug/neighborhoods required
GET /categories required
GET /brands required
GET /segments required

Health

GET /health — served at the root of the API host, without the /api/v1 prefix (also available as /healthz). Use it for uptime checks and load-balancer probes.

curl https://api.mapdove.com/health
{ "status": "ok", "db": true, "version": "0.1.0" }

db is false if the database is unreachable.

Public stats

GET /public/stats — headline counts of the dataset, used on the marketing site. No authentication.

curl https://api.mapdove.com/api/v1/public/stats
{ "cities": 5, "places": 1235, "visits_tracked": 123456789, "hexes": 2417 }

visits_tracked is the total number of synthetic visits in the demo dataset.

Plans

GET /plans — the public plan catalog with limits. No authentication. -1 means unlimited; price_monthly is in USD and null for “contact us”.

curl https://api.mapdove.com/api/v1/plans
[
  {
    "id": "pro",
    "name": "Pro",
    "price_monthly": 149,
    "limits": {
      "history_days": 365, "analyses_per_month": 500, "api_calls_per_month": 10000,
      "api_keys": 3, "seats": 5, "exports": true, "cities": -1, "alerts": 10
    },
    "features": ["12 months of history", "500 site analyses / month", "CSV export", "REST API (10k calls)", "5 seats", "Visit alerts"]
  }
]

The response contains all four plans (free, pro, business, enterprise). See Plans and limits.

Cities

List cities

GET /cities — all demo markets.

curl https://api.mapdove.com/api/v1/cities \
  -H "Authorization: Bearer $MAPDOVE_KEY"
const cities = await fetch('https://api.mapdove.com/api/v1/cities', {
  headers: { Authorization: `Bearer ${key}` },
}).then((r) => r.json());
cities = requests.get(f"{BASE}/cities", headers=H, timeout=30).json()
[
  {
    "id": 1, "slug": "austin", "name": "Austin", "region": "Texas", "country": "US",
    "timezone": "America/Chicago", "currency": "USD", "units": "imperial",
    "center": [-97.7431, 30.2672], "zoom": 10.6,
    "bbox": [-97.9201, 30.1561, -97.5785, 30.5412],
    "description": "Fast-growing tech hub with a dense core, strong suburban growth north along the I-35 and US-183 corridors.",
    "places": 247, "population": 668641
  }
]

center is [lng, lat]; bbox is [minLng, minLat, maxLng, maxLat] of the study area.

City detail

GET /cities/:slug — a city plus data range, city KPIs, category and neighborhood summaries.

Param Description
slug austin, houston, phoenix, miami or dubai 
curl https://api.mapdove.com/api/v1/cities/austin \
  -H "Authorization: Bearer $MAPDOVE_KEY"
{
  "id": 1, "slug": "austin", "name": "Austin", "currency": "USD", "units": "imperial",
  "places": 247, "population": 668641,
  "data_range": { "from": "2025-11-01", "to": "2026-10-31" },
  "kpis": {
    "visits_30d": 4182310, "visits_prev_30d": 4079555, "change_pct": 2.5,
    "median_income": 92140, "daytime_pop": 811204
  },
  "categories": [
    { "slug": "coffee", "name": "Coffee & Cafés", "color": "#92400e", "places": 34, "visits_30d": 371820, "change_pct": 1.2 }
  ],
  "neighborhoods": [
    { "id": 1, "name": "Downtown", "population": 58210, "median_income": 116400, "places": 31 }
  ]
}

(Trimmed: the detail also includes every City field.)

Hex grid

GET /cities/:slug/hexes — the city’s hexagonal grid (≈0.8 km² cells) as a GeoJSON FeatureCollection of polygons. Use it to build choropleth maps or to join your own data by id.

curl https://api.mapdove.com/api/v1/cities/austin/hexes \
  -H "Authorization: Bearer $MAPDOVE_KEY" -o austin-hexes.geojson
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "Polygon", "coordinates": [[[-97.7452, 30.2651], [-97.7401, 30.2651], "…"]] },
      "properties": {
        "id": 12, "population": 1520, "households": 600, "median_income": 91000, "median_age": 34.2,
        "daytime_pop": 3000, "density": 1880, "pct_college": 45.1, "pct_family": 31.0,
        "rent_index": 62.3, "traffic_index": 55.0, "growth_rate": 0.031,
        "segment": "urban-professionals", "neighborhood": "Downtown"
      }
    }
  ]
}
Property Meaning
density residents per km²
daytime_pop people present during the day
pct_college, pct_family percent of adults with a degree; percent family households
rent_index, traffic_index 0–100 within the city
growth_rate annual population growth as a fraction (0.031 = 3.1%)
segment lifestyle segment slug

Neighborhoods

GET /cities/:slug/neighborhoods — neighborhood polygons with summary properties.

curl https://api.mapdove.com/api/v1/cities/miami/neighborhoods \
  -H "Authorization: Bearer $MAPDOVE_KEY"
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "MultiPolygon", "coordinates": ["…"] },
      "properties": { "id": 50, "name": "Brickell", "population": 41820, "median_income": 108300, "places": 24 }
    }
  ]
}

Neighborhood boundaries in the demo are geometric (Voronoi cells), not official boundaries.

Categories

GET /categories — the 14 place categories.

curl https://api.mapdove.com/api/v1/categories \
  -H "Authorization: Bearer $MAPDOVE_KEY"
[
  { "id": 1, "slug": "coffee", "name": "Coffee & Cafés", "color": "#92400e", "icon": "coffee", "places": 170 },
  { "id": 2, "slug": "grocery", "name": "Grocery", "color": "#16a34a", "icon": "shopping-basket", "places": 110 }
]

places is the count across all cities. Slugs: coffee, grocery, qsr, dining, fitness, apparel, pharmacy, home, electronics, department, cinema, hotel, fuel, mall. Model parameters per category are listed in Methodology.

Brands

GET /brands — the 31 fictional chains, optionally filtered by category.

Param Description
category optional category slug 
curl "https://api.mapdove.com/api/v1/brands?category=coffee" \
  -H "Authorization: Bearer $MAPDOVE_KEY"
[
  { "id": 1, "slug": "bean-republic", "name": "Bean Republic", "category": "coffee", "color": "#6f4e37", "price_tier": 2, "locations": 40 },
  { "id": 2, "slug": "copperline-coffee", "name": "Copperline Coffee", "category": "coffee", "color": "#b45309", "price_tier": 3, "locations": 41 }
]

price_tier runs from 1 (value) to 4 (premium); locations counts all cities. Brand performance is under Market endpoints.

Segments

GET /segments — the eight lifestyle segments.

curl https://api.mapdove.com/api/v1/segments \
  -H "Authorization: Bearer $MAPDOVE_KEY"
[
  {
    "slug": "urban-professionals", "name": "Urban Professionals", "color": "#14b8a6",
    "description": "Well-paid singles and couples in dense cores; coffee, fitness, dining, weekday daytime traffic."
  }
]

See Lifestyle segments for definitions.