API reference

Reach for it when the question is “which place is this point in?”

• Reverse geocoding to administrative areas — a coordinate becomes the country, region (state, province) and municipality (city, district or county) that contain it, as names plus ISO 3166-1 / ISO 3166-2 codes. Worldwide, from OpenStreetMap boundaries.
• Geofencing against your own polygons — upload GeoJSON delivery zones, service areas or sales territories and test a point against them in the same call as the administrative layers.
• Jurisdiction and region checks — which country or region a user, order or device is in, for pricing, availability, tax or licensing rules.
• Enriching location data — tag GPS pings, orders or sign-ups with region codes, and optionally an H3 cell index or Google Plus Code.
• Privacy-sensitive workloads — looked-up coordinates are never stored.

Not a fit

• Street addresses, postcodes or place search. This is not forward geocoding, and reverse lookups stop at the municipality, not the street.
• Routing, distances or map tiles.
• Boundary geometry itself. It answers containment; it does not return the reference polygons.
• Many coordinates in one request. One request is one coordinate.
• Enter/exit events. It answers which zones contain a point now; tracking transitions between calls is up to your code.

Boundaries follow OpenStreetMap. For a legally binding jurisdiction decision, confirm against the authoritative source.

Two mechanisms, and the difference decides what a program can do.

• API key — Authorization: Bearer <key>. A 64-character hex string, no prefix. This is what a program uses.
• Session cookie — issued by an interactive Google sign-in in a browser. An automated client cannot obtain one.

A key is enough for lookups and for managing boundary sets. It is not enough to mint keys, read usage, or manage billing.

Create a key on the dashboard, or call GET https://api.atlasfetch.xyz/demo/key for a shared public one — no signup, but its 1,000 lookups a month and its rate limit are pooled across every anonymous user. Use it to try things, not to ship.

GET https://api.atlasfetch.xyz/location/lookup?lat=51.5072&lng=-0.1276
Authorization: Bearer <key>

curl -H "Authorization: Bearer $ATLASFETCH_KEY" \
  "https://api.atlasfetch.xyz/location/lookup?lat=51.5072&lng=-0.1276"

{
  "base": {
    "country":   { "code": "GB",     "name": "United Kingdom" },
    "region":    { "code": "GB-ENG", "name": "England" },
    "municipal": { "code": "GB-WSM", "name": "City of Westminster" }
  },
  "sets": {
    "delivery_zones": [
      { "name": "Zone A", "properties": { "category": "express" } }
    ]
  },
  "errors": []
}

Guarantees you can rely on

• errors[] is always present, empty or not. Read it unconditionally.
• A layer that matched nothing is null, not absent.
• encoded is absent entirely unless encode was asked for.
• Every response carries X-Lookups-Remaining.
• Boundaries are identified by codes, never OSM ids — ISO 3166-1 for country, ISO 3166-2 for region, and for municipal the official ISO code where OSM carries one, otherwise a generated B-<country>-<n>.
• municipal is the finest unit available, not a consistent kind of thing. Los Angeles returns a city; rural Kansas returns Barton County. Where a country’s fine tier is patchy, a coarser complete tier answers instead — a county beats null for most uses. Do not assume the value names a city.

A request is exactly one lookup regardless of how many layers, sets or grid codes it touches. Metering happens before matching, so a call that matches nothing still costs a lookup — the work was done either way. A request rejected with 400 or 429 is not billed.

A set you cannot query does not fail the request. It is skipped, an entry is appended to errors[], and the status stays 200. A set is only queryable when it is marked available and granted to the key making the call.

"errors": [
  { "type": "access", "message": "Set 'zones' is not granted to key 'prod'" }
]

type is access (a set was skipped) or usage (quota exhausted, mirroring a 402).

The looked-up point can be returned as a Google Plus Code and/or an H3 cell index. Not metered, not plan-gated.

GET https://api.atlasfetch.xyz/location/lookup?lat=51.5072&lng=-0.1276&encode=h3,pluscode

"encoded": { "h3": "89195da49b7ffff", "pluscode": "9C3XGV4C+VX" }

They are output only

pluscode= and h3= are not accepted as a location; sending one returns 400. That is deliberate, not a missing feature.

A Plus Code and an H3 index name areas, not points. A length-4 Plus Code is a 111 km square; an H3 cell at resolution 4 is 52 km across. Accepting one as the location would mean picking a representative point inside it and returning whichever boundary contains that point as though it were the answer — one of several equally defensible answers, with no way for you to tell which situation you were in.

If you have a cell and want a lookup, decode it yourself and decide what its centre means for your use case. That keeps the judgement where the context is.

Picking a precision

Plus Code widths are at the equator. pluslen=9 is invalid — 9 is not a Plus Code length.

Your own polygons, grouped into named sets, matched in the same call as the reference layers. These endpoints accept an API key or a session.

No authentication, no metering.

Rate limiting is per key, per second. Quota is per account, per month.

We do not store the coordinates you look up. Usage metering records the endpoint, the key and a timestamp — never the point.

Reference boundaries derive from OpenStreetMap under the ODbL. Attribution and share-alike obligations pass through to you — see data attribution. Your own uploaded boundaries are private to your account and are never returned to anyone else.