Endpoint reference

List areas at one level

curl "https://geoapi.mcpke.dev/api/v1/areas?admin_level=1&limit=1"

{
  "results": [
    {
      "id": 9,
      "country_code": "ID",
      "admin_level": 1,
      "level_name": "Provinsi",
      "name": "Daerah Istimewa Yogyakarta",
      "slug": "daerah-istimewa-yogyakarta",
      "geom_source": "cod-ab",
      "area_km2": 3170.65,
      "population": 3793052,
      "density": 1196.3,
      "centroid": { "lng": 110.4, "lat": -7.87 },
      "bbox": [110.0, -8.2, 110.85, -7.55]
    }
  ],
  "meta": { "took_ms": 6, "total_results": 1, "total_available": 38, "limit": 1, "offset": 0 }
}

level_name is the label the country itself uses for that level, so it is returned in the local administrative vocabulary rather than translated into a generic tier name. meta.total_available is the row count matching the query before paging, which is what makes exhaustive iteration possible.

bbox is [min_lng, min_lat, max_lng, max_lat] — GeoJSON order, and the same order the bbox query parameter accepts, so a response can be fed straight back into a query or into a map client's fitBounds. centroid is guaranteed to lie on the area rather than at its centre of mass, which for an archipelago or a crescent-shaped area is not the same point: use it to place a label or a marker, and bbox to frame a view. Both are omitted for an area with no usable geometry.

One area, with its lineage, subdivisions and provenance

curl "https://geoapi.mcpke.dev/api/v1/areas/42"

{
  "results": {
    "id": 42,
    "country_code": "ID",
    "admin_level": 2,
    "name": "Kota Banda Aceh",
    "slug": "kota-banda-aceh",
    "geom_source": "cod-ab",
    "area_km2": 61.36,
    "population": 257635,
    "density": 4198.5,
    "centroid": { "lng": 95.32, "lat": 5.55 },
    "bbox": [95.27, 5.51, 95.38, 5.61],
    "ancestors": [
      { "id": 1, "name": "Aceh", "admin_level": 1, "level_name": "Provinsi", "level_name_en": "Province" }
    ],
    "children": {
      "count": 9,
      "with_population": 9,
      "level": 3,
      "level_name": "Kecamatan",
      "level_name_en": "District"
    },
    "resolved": { "area_id": 42, "value": 257635, "year": 2024, "method": "projected", "source_id": "geonames" },
    "observations": [
      { "id": 501, "area_id": 42, "source_id": "geonames", "value": 257635, "year": 2024, "method": "projected" },
      { "id": 502, "area_id": 42, "source_id": "kontur",   "value": 115131, "year": 2023, "method": "modelled" }
    ]
  },
  "meta": { "took_ms": 9 }
}

observations is every figure on record for the area, unfiltered. population at the top level is the resolved value produced by the precedence rule — not an average and not the most recent import, and resolved is the row that produced it, so a client showing one number can say where the number came from. source_id values map to a provider, a licence, and a required attribution string on Data sources.

ancestors runs outermost-first and excludes the area itself, so it renders as a breadcrumb without slicing; it is an empty array for a top-level area, never null. children is a summary rather than a list — count is what lets you decide whether to offer a subdivisions control at all, instead of requesting a list for every leaf area that will always come back empty, and it matches the total_available of /v1/areas?parent_id={id}. level is absent exactly when count is 0.

resolved is absent for an area with no observation, and so is population — never 0. "No figure recorded" and "nobody lives here" are different claims, and this API does not conflate them.

Boundary geometry

curl "https://geoapi.mcpke.dev/api/v1/areas/42?format=geojson&simplify=100"

Returns a bare GeoJSON Feature, with bbox as a top-level member per RFC 7946. That bbox describes the unsimplified area: simplify reduces the geometry that ships, never the footprint it is reported to occupy.

Geometry is deliberately excluded from the default JSON response — a single top-level area can run to megabytes, and the common case wants the figures rather than the shape. If you only need to know where an area is, read bbox/centroid from the ordinary response rather than requesting a polygon; for rendering a whole viewport, use the tile endpoint below.

Resolved figure

curl "https://geoapi.mcpke.dev/api/v1/population?area_id=42"

{
  "results": [
    { "area_id": 42, "value": 257635, "year": 2024, "method": "projected", "source_id": "geonames" }
  ],
  "meta": { "took_ms": 3, "total_results": 1 }
}

The resolution order is fixed and identical for every area: method (census > projected > modelled), then source priority, then the most recent reference year. An observation that falls far below the combined total of the area's own sub-divisions is excluded from this figure and flagged, rather than published or deleted — see how observations are resolved.

Coverage

curl "https://geoapi.mcpke.dev/api/v1/coverage?country=ID"

{
  "results": [
    {
      "country_code": "ID",
      "admin_level": 2,
      "source_id": "geonames",
      "total_areas": 522,
      "covered_areas": 340,
      "coverage_pct": 65.13,
      "census_count": 0,
      "projected_count": 340,
      "modelled_count": 0
    },
    {
      "country_code": "ID",
      "admin_level": 2,
      "source_id": "kontur",
      "total_areas": 522,
      "covered_areas": 522,
      "coverage_pct": 100,
      "census_count": 0,
      "projected_count": 0,
      "modelled_count": 522
    }
  ],
  "meta": { "took_ms": 5, "total_results": 2 }
}

Coverage is reported per country, per administrative level, and per source, because it varies sharply across all three — the two rows above are the same 522 areas, and one provider covers all of them while the other covers two thirds. Reading a single row as "the" coverage of a level would be wrong in both directions.

coverage_pct measures the presence of a figure, not its accuracy; the two are independent and should be read separately. A level can be 100% covered entirely by modelled estimates, which is a different claim from 100% covered by census counts — census_count, projected_count and modelled_count are what tell them apart.

Extent

curl "https://geoapi.mcpke.dev/api/v1/extent"

{
  "results": {
    "min_lng": 95.01, "min_lat": -11.01,
    "max_lng": 141.02, "max_lat": 6.08,
    "countries": ["ID"],
    "area_count": 7616
  },
  "meta": { "took_ms": 4, "countries": 1 }
}

The bounding box of what is actually imported, optionally narrowed with ?country=. Use it to frame a viewport from the data rather than hardcoding a region — as coverage expands, a client built on this widens by itself.

curl "https://geoapi.mcpke.dev/api/v1/places?bbox=95.30,5.54,95.34,5.58&limit=2"

{
  "results": [
    {
      "id": 1841,
      "source_id": "geoapi-places",
      "name": "A3 GYM",
      "category": "gym",
      "address": "Jl. Teuku Umar No. 12",
      "latitude": 5.5561,
      "longitude": 95.3187,
      "rating": 4.6,
      "review_count": 128
    }
  ],
  "meta": { "took_ms": 14, "total_results": 2 }
}

Every place carries latitude and longitude outright, so the plain JSON response is already mappable. format=geojson returns the same records as a point FeatureCollection instead, for handing straight to a mapping library without a transform step.

area_id is the deepest administrative area whose boundary contains the point — a cached spatial answer, not an attribution. A business is not a property of a village the way a population figure is; it is at a coordinate, and this records which polygon that coordinate fell in. It is omitted when the point lies outside every boundary held. Querying ?area_id= walks downwards, so asking about a regency returns the businesses attached to its villages.

Point a map at the source

map.addSource("areas", {
  type: "vector",
  url: "https://geoapi.mcpke.dev/api/v1/tiles/areas.json",
});

Prefer this over hardcoding a tile template. The descriptor carries the tile URL, the zoom range, the data's bounds, the property set each feature holds, and the attribution the underlying licences require — all of which are server-side facts that change as coverage expands. A client that copies them locally is a client that silently disagrees with the server the next time they change.

The descriptor

curl "https://geoapi.mcpke.dev/api/v1/tiles/areas.json"

{
  "tilejson": "3.0.0",
  "name": "geoapi-areas",
  "scheme": "xyz",
  "format": "pbf",
  "tiles": ["https://geoapi.mcpke.dev/api/v1/tiles/areas/{z}/{x}/{y}.mvt"],
  "minzoom": 0,
  "maxzoom": 16,
  "bounds": [95.01, -11.01, 141.02, 6.08],
  "center": [118.01, -2.46, 2],
  "attribution": "…",
  "vector_layers": [
    {
      "id": "areas",
      "minzoom": 0,
      "maxzoom": 16,
      "fields": {
        "id": "Number", "country_code": "String", "name": "String",
        "admin_level": "Number", "area_km2": "Number",
        "population": "Number", "density": "Number"
      }
    },
    {
      "id": "area_labels",
      "minzoom": 0,
      "maxzoom": 16,
      "fields": { "id": "Number", "name": "String", "admin_level": "Number" }
    }
  ]
}

Served bare, with no results/meta wrapper, so it can be handed directly to a mapping library. bounds reflects what is actually imported, so it widens by itself as coverage grows.

Tile behaviour

The server picks which administrative level to serve from the requested zoom, so a client never needs a level switcher — request tiles and draw the layer named areas at every zoom. A tile with no features returns 204 No Content. Vector tiles have no null type: an area with no recorded population omits the key entirely, so test for presence rather than for zero. Tiles are metered on their own, much larger rate-limit budget than the JSON endpoints, since one viewport is several requests.

Tile features deliberately do not carry bbox, and their geometry is clipped to the tile. To frame a view on a whole area, read bbox from /v1/areas/{id} rather than deriving it from a tile feature — an area larger than one tile would otherwise give you the wrong rectangle, quietly.

Draw name labels from area_labels, not from areas. Because polygons are clipped per tile, a symbol layer over the polygon layer places one label in every tile an area crosses — a regency spanning six tiles is labelled six times, and no client-side setting can deduplicate across tiles. The area_labels layer holds exactly one point per area, in the tile containing its centroid.