Boundaries part-of

GET /v1/boundaries/part-of answers "what boundaries is this place inside?" Give it a Place ID, a coordinate, or an OSM object, and it returns the containing city, township, county, state and country, plus optionally the ZIP-like postal area, the timezone, or OSM polygons such as a national park. Use it to enrich a location with its jurisdictions, or to fetch a boundary polygon for a map.

How it worksCopy Anchor Link

The gateway answers this route directly from PostGIS; no geocoding Engine or Valhalla is involved.

1. It resolves the lookup to a point. A lat/lon pair is used as is. A gp:osm: Place ID or osm_id/osm_type pair is looked up in the Nominatim placex table and reduced to a representative point on its surface. A gp:pc: Place ID is looked up in the postal polygons.
2. administrative: every OSM boundary with admin_level 2 to 11 whose polygon covers the point, smallest first. For an administrative Place ID, only that boundary and its ancestors are kept.
3. postal_code: the Census ZCTA5 (US) or StatCan FSA (Canada) polygon covering the point.
4. timezone: the timezone-boundary-builder polygon covering the point, with place_id gp:tz:<tzid>.
5. Other OSM polygon layers (neighborhood, place, region, political, historic, protected_area, national_park, aboriginal_lands, census, school_district, forest, hazard, regional_park, religious_administration, low_emission_zone, public_transport, traditional): every polygon of that type covering the point. protected_area includes leisure=nature_reserve; national_park is boundary=national_park, or a nature reserve named "... National Park".
6. religious, municipality, barony, town, health and historic:administrative are accepted but have no data layer: they return nothing.
7. boundaries=all expands to every type, and there is no cap on how many types you list (duplicates are collapsed). The top-level layers array reports each requested type with layer (a data layer exists) and within (how many of its boundaries contain the point).
8. Names for each feature (state, county, city, ...) come from the chain of containing administrative boundaries.

Data sources: OpenStreetMap (Geofabrik US and Canada extract, imported by Nominatim), Census ZCTA5, StatCan FSA boundaries, and timezone-boundary-builder (ODbL).

Quick startCopy Anchor Link

curl -s "https://api.data.graphitelab.ai/v1/boundaries/part-of?lat=39.7684&lon=-86.1581&apiKey=$GRAPHITE_API_KEY"

Response (trimmed to the first feature; the full response also has Center Township, Marion County, Indiana and the United States):

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "name": "Indianapolis",
        "country": "United States",
        "country_code": "us",
        "state": "Indiana",
        "state_code": "IN",
        "iso3166_2": "US-IN",
        "county": "Marion County",
        "county_district": "Center Township",
        "city": "Indianapolis",
        "lon": -86.0932472869693,
        "lat": 39.7798447,
        "place_id": "gp:osm:r18438530",
        "datasource": {
          "sourcename": "openstreetmap",
          "attribution": "© OpenStreetMap contributors",
          "license": "Open Database License",
          "url": "https://www.openstreetmap.org/copyright",
          "raw": { "osm_id": 18438530, "osm_type": "r", "admin_level": 8 }
        }
      },
      "geometry": { "type": "Point", "coordinates": [-86.093247, 39.779845] },
      "bbox": [-86.3281207, 39.6321626, -85.9380401, 39.9275253]
    }
  ]
}

ParametersCopy Anchor Link

Use exactly one lookup method: id, lat with lon, or osm_id with osm_type.

Full parameter reference

ResponseCopy Anchor Link

The response is a GeoJSON FeatureCollection with one feature per containing boundary. Administrative features come smallest first (city before county before state before country).

This endpoint has no rank object, distances or times.

Differences from GeoapifyCopy Anchor Link

• empty: religious, municipality, barony, town, health and historic:administrative are accepted but have no data layer (layer: false in layers). The X-Boundaries-Note header is sent only when at least one requested type has no data layer: "Some requested boundary types have no data layer: see layers in the response (layer: false)."

• extra: the types protected_area, national_park, aboriginal_lands, census, school_district, forest, hazard and regional_park, the value boundaries=all, no cap on the number of types (Geoapify allows 10), the layers summary and boundary_type.

• empty: optional descriptive fields (formatted, address_line1, address_line2, categories, name_international, population, the timezone descriptor object, ...) are never returned. A timezone boundary feature is returned when you request boundaries=timezone.

• unsupported: id resolves only gp:osm: and gp:pc: Place IDs. gp:addr:, gp:tz:, gp:iso: and Geoapify hex IDs return an empty FeatureCollection (gp:tz:<tzid> is a returned place_id on timezone features but is not an input). Malformed gp: IDs return 400.

• extra: place_id uses our gp:<kind>:<key> format, and datasource describes the OSM, ZCTA5, FSA or timezone-boundary-builder source.

• approximated: geometry_N simplification uses PostGIS ST_SimplifyPreserveTopology with a tolerance of N / 111320 degrees, so accuracy differs slightly from Geoapify.

US and Canada notesCopy Anchor Link

• Administrative boundaries are OSM, so levels are sparse and vary by place. Indianapolis returns a city and a township, while the Montreal example returns a city and an urban agglomeration as county.

• US postal boundaries are Census ZCTA5, which approximate ZIP codes but are not USPS ZIPs. PO-box-only ZIPs have no polygon.

• Canadian postal boundaries are StatCan FSA (the first three characters, like H3B). Full six-character postal codes have no polygon here.

• The lang parameter helps in bilingual areas: Canadian boundaries often have name:fr.

More examplesCopy Anchor Link

curl -s "https://api.data.graphitelab.ai/v1/boundaries/part-of?lat=45.5019&lon=-73.5674&boundaries=administrative,postal_code&geometry=geometry_5000&apiKey=$GRAPHITE_API_KEY"

Errors and limitsCopy Anchor Link

An ID or OSM object that does not resolve, or a point outside any boundary, returns 200 with an empty FeatureCollection, not 404.