Concepts

Place IDs, rank, datasource, the error shape, response formats and how this API differs from Geoapify.

Place IDs

Geoapify's place_id is an opaque blob. Ours is readable and typed: gp:<kind>:<key> (ADR 0006). The gateway routes an ID to the right engine by its prefix, and IDs stay stable across monthly Data Releases while the thing still exists.

Kind	Meaning	Example
`gp:addr`	Address Point (Canonical Address)	`gp:addr:canonical:37388970`
`gp:osm`	OpenStreetMap node, way or relation (`n`, `w`, `r` plus id)	`gp:osm:r161816`
`gp:pc`	Postcode: US ZIP or Canadian code	`gp:pc:US-46204`, `gp:pc:CA-K1A0A1`
`gp:tz`	Timezone (IANA name)	`gp:tz:America/Indiana/Indianapolis`
`gp:iso`	Stored isoline	`gp:iso:<id>`

You get a Place ID in the place_id property of geocoding results. Where it can be used as input:

Boundaries. id on /boundaries/part-of and /boundaries/consists-of accepts gp:osm (administrative) and gp:pc (postal) IDs. Other kinds return an empty FeatureCollection. gp:tz:<tzid> appears as the returned place_id of timezone features (boundaries=timezone) but does not resolve as an id.
Isolines. GET /isoline?id=<id> retrieves a stored result.

Geoapify hex place IDs are not accepted.

Rank, confidence and match type

Geoapify returns a rank object on each result. Ours fills the same fields from the Geocoding Waterfall's own scoring (ADR 0002): libpostal parses the input, then an exact Canonical Address match, then interpolation between neighbors, then fuzzy search. All scores are on a 0 to 1 scale.

Field	Meaning
`confidence`	Overall match score. 1 is a full match.
`confidence_city_level`, `confidence_street_level`, `confidence_building_level`	Score at each level.
`match_type`	One of `full_match`, `inner_part`, `match_by_building`, `match_by_street`, `match_by_postcode`, `match_by_city_or_disrict` (sic, as in Geoapify), `match_by_country_or_state`.
`importance`	Present on some results. Address Point matches use 1; interpolated points use 0.5.

The X-Geo-Stage response header names the Waterfall stage that produced the first result. bias never changes rank values. rank.popularity is never returned.

Datasource

Every result carries a datasource for the source it actually came from, for provenance as well as licensing.

OSM-derived (gp:osm:*): attribution is "© OpenStreetMap contributors" under the Open Database License.
Address Point (gp:addr:*): sourcename is the Source Record source (nad, nar, overture) with each licence's attribution. When several sources agree, sourcename joins them with + (for example nad+overture) and sources[] lists each one. This sources[] list is an addition to Geoapify's shape.
Interpolated points use sourcename: canonical-neighbours.

Surface the attribution wherever you display results.

Error shape

Errors from the gateway are JSON with three fields:

{ "statusCode": 400, "error": "Bad Request", "message": "Parameter 'text' is required" }

Status	`error`
400	Bad Request
401	Unauthorized
404	Not Found
409	Conflict
413	Payload Too Large
429	Too Many Requests (over 60 per minute)
500	Internal Server Error
502	Bad Gateway
503	Service Unavailable
504	Gateway Timeout (`Database query timed out`)

Formats

Many endpoints take a format parameter. Availability, from the spec:

Endpoint	`format` values (default first)
`/geocode/search`, `/geocode/reverse`, `/geocode/autocomplete`	`geojson`, `json`, `xml`
`/postcode/search`, `/postcode/list`	`geojson`, `json`, `xml`
`/routing`	`geojson`, `json`, `xml`
`/isoline`	`geojson`, `topojson`, `geobuf` (binary)
`/geodata/elevation`	`json`, `geojson`

The other endpoints (boundaries, route matrix, map matching, route planner, timezone) have no format parameter. geojson responses are GeoJSON; check each endpoint page for the exact content type.

The x-geo-deviation convention

Wherever this API differs from Geoapify, the spec marks the operation or parameter with an x-geo-deviation list and a matching Deviation (kind) line in the description. Kinds:

Kind	Meaning
`unsupported`	Geoapify behavior we do not offer.
`empty`	Field exists but is always empty or null.
`extra`	Something we add that Geoapify does not have.
`approximated`	Same field, computed differently or less precisely.
`ignored`	Parameter accepted and ignored.

Treat these as the list of things to re-test when migrating.

Concepts

Place IDsCopy Anchor Link

Rank, confidence and match typeCopy Anchor Link

DatasourceCopy Anchor Link

Error shapeCopy Anchor Link

FormatsCopy Anchor Link