Boundaries consists-of

GET /v1/boundaries/consists-of takes the Place ID of a boundary and returns the boundaries contained inside it, as a GeoJSON FeatureCollection. Use it to list the counties of a state, the subdivisions of a province, or the postal code areas inside a county. Get the parent id from /boundaries/part-of (the properties.place_id of the boundary you want).

How it worksCopy Anchor Link

The gateway answers this route with SQL only: no Geocoding Waterfall, Valhalla or VROOM.

1. The id is decoded and resolved to a parent geometry. gp:osm:... ids look up the OpenStreetMap boundary in the Nominatim placex table; gp:pc:... ids look up a postal polygon.
2. For boundary=administrative, it selects OpenStreetMap administrative boundaries (admin_level 2 to 11) that are deeper than the parent and whose representative point lies inside the parent. sublevel picks the N-th distinct admin_level found below the parent.
3. For boundary=postal_code, it selects ZCTA5 polygons (US, Census) or FSA polygons (Canada, Statistics Canada) whose representative point lies inside the parent.
4. Results are ordered by name (administrative) or code (postal). Polygon geometry is simplified with PostGIS ST_SimplifyPreserveTopology.

Administrative data comes from the Geofabrik US and Canada OpenStreetMap extract, loaded through Nominatim.

Quick startCopy Anchor Link

All of Indiana's counties:

curl -s "https://api.data.graphitelab.ai/v1/boundaries/consists-of?id=gp:osm:r161816&apiKey=$GRAPHITE_API_KEY"

Response (trimmed to the first feature of 92):

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "name": "Adams County",
        "country": "United States",
        "continent": "North America",
        "country_code": "us",
        "state": "Indiana",
        "state_code": "IN",
        "iso3166_2": "US-IN",
        "county": "Adams County",
        "lon": -84.93671397818535,
        "lat": 40.745785850000004,
        "place_id": "gp:osm:r1797289",
        "datasource": {
          "sourcename": "openstreetmap",
          "attribution": "© OpenStreetMap contributors",
          "license": "Open Database License",
          "url": "https://www.openstreetmap.org/copyright",
          "raw": {
            "osm_id": 1797289,
            "osm_type": "r",
            "admin_level": 6,
            "wikidata": "Q351808",
            "wikipedia": "en:Adams County, Indiana"
          }
        }
      },
      "geometry": { "type": "Point", "coordinates": [-84.936714, 40.745786] },
      "bbox": [-85.0738683, 40.568253, -84.80217, 40.9225978]
    }
  ]
}

ParametersCopy Anchor Link

Full parameter reference

ResponseCopy Anchor Link

A GeoJSON FeatureCollection. Each feature has properties, geometry and bbox.

• place_id: opaque string of the form gp:<kind>:<key>. Administrative features use gp:osm:r161816; postal features use gp:pc:US-46201. Pass it back as id to walk down another level.
• name, country, country_code, state, state_code, iso3166_2, county and similar address fields describe the boundary and its parents.
• lon and lat: the boundary's representative point.
• datasource: where the boundary came from. OpenStreetMap boundaries cite "© OpenStreetMap contributors" under the Open Database License. Postal features use census-zcta5 or statcan-fsa and cite their source.
• datasource.raw: source identifiers. Administrative features carry osm_id, osm_type, admin_level and, when present, wikidata, wikipedia, ISO3166-2. Postal features carry code.
• Postal features also carry postcode and postal_code.
• geometry: a Point by default, or a simplified Polygon or MultiPolygon with geometry_*.

This endpoint has no rank field and no distances or times.

Differences from GeoapifyCopy Anchor Link

• empty: only administrative and postal_code boundaries have data. Other boundary values, unknown ids and non-boundary Place IDs (gp:addr, gp:tz, gp:iso) return an empty FeatureCollection, not 404. Other boundary types also set the X-Boundaries-Note response header: "consists-of has data for administrative and postal_code only".

• extra: datasource.raw is a small set of source identifiers instead of the full OpenStreetMap tag set, and many optional Geoapify properties (formatted, categories, website, name_international, timezone and others) are not populated. Postal features add postcode and postal_code.

• approximated: sublevel counts distinct admin_level values present below the parent, not parent level plus N. Containment is decided by each child's representative point, not by polygon overlap.

Geoapify's own place ids are not understood; use ids returned by this API.

US and Canada notesCopy Anchor Link

• US postal results are Census ZCTA5 polygons, which approximate ZIP codes. PO-box-only ZIPs have no polygon.
• Canadian postal results are FSA polygons (the first three characters of a postal code), from Statistics Canada.
• OpenStreetMap admin levels are sparse and differ by region. Indiana's counties are level 6; Ontario's children come back as OpenStreetMap subdivisions such as "Central Ontario". Use sublevel to step down.
• Names follow lang. Ask for fr to get French names where OpenStreetMap has them.

More examplesCopy Anchor Link

curl -s "https://api.data.graphitelab.ai/v1/boundaries/consists-of?id=gp:osm:r68841&apiKey=$GRAPHITE_API_KEY"

Errors and limitsCopy Anchor Link

Limits: id is 3 to 2048 characters, and sublevel is 1 to 20.