Skip to content
Plaza Plaza Docs
GuidesBlogPlaygroundDashboard
API Reference

Geocode

Forward geocode an address
client.geocode.forward(GeocodeForwardParams { q, bbox, country_code, 6 more } query, RequestOptionsoptions?): GeocodeResult { features, type }
GET/api/v1/geocode
Forward geocode an address
client.geocode.forwardPost(GeocodeForwardPostParams { q, bbox, country_code, 6 more } params, RequestOptionsoptions?): GeocodeResult { features, type }
POST/api/v1/geocode
Reverse geocode a coordinate
client.geocode.reverse(GeocodeReverseParams { format, lang, lat, 5 more } query?, RequestOptionsoptions?): ReverseGeocodeResult { features, type }
GET/api/v1/geocode/reverse
Reverse geocode a coordinate
client.geocode.reversePost(GeocodeReversePostParams { format, lang, lat, 5 more } params?, RequestOptionsoptions?): ReverseGeocodeResult { features, type }
POST/api/v1/geocode/reverse
Autocomplete a partial address
client.geocode.autocomplete(GeocodeAutocompleteParams { q, country_code, format, 5 more } query, RequestOptionsoptions?): AutocompleteResult { features, type }
GET/api/v1/geocode/autocomplete
Autocomplete a partial address
client.geocode.autocompletePost(GeocodeAutocompletePostParams { q, country_code, format, 5 more } params, RequestOptionsoptions?): AutocompleteResult { features, type }
POST/api/v1/geocode/autocomplete
Batch geocode multiple addresses
client.geocode.batch(GeocodeBatchParams { addresses } body, RequestOptionsoptions?): GeocodeBatchResponse { count, results }
POST/api/v1/geocode/batch
ModelsExpand Collapse
AutocompleteResult { features, type }

GeoJSON FeatureCollection of autocomplete suggestions for partial address input. Optimized for low-latency type-ahead UIs. Content-Type: application/geo+json.

features: Array<GeocodingFeature { geometry, properties, type } >

Autocomplete suggestions ordered by relevance

geometry: GeoJsonGeometry { coordinates, type }

GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

coordinates: Array<number> | Array<Array<number>> | Array<Array<Array<number>>> | Array<Array<Array<Array<number>>>>

Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

One of the following:
Array<number>
Array<Array<number>>
Array<Array<Array<number>>>
Array<Array<Array<Array<number>>>>
type: "Point" | "LineString" | "Polygon" | 3 more

Geometry type

One of the following:
"Point"
"LineString"
"Polygon"
"MultiPoint"
"MultiLineString"
"MultiPolygon"
properties: Properties { display_name, category, city, 18 more }

Geocoding result properties

display_name: string

Formatted address or place name

category?: string | null

POI category (e.g. restaurant, cafe, park). Present for place results.

city?: string | null

City or town name. Present for address results.

confidence?: number | null

Interpolation confidence (0-1). Present only for interpolated results.

maximum1
minimum0
country?: string | null

Country name. Present for reverse geocode address results.

country_code?: string | null

ISO 3166-1 alpha-2 country code

maxLength2
minLength2
distance_m?: number | null

Distance from the query point in meters (reverse geocode / nearby only)

full_address?: string | null

Complete formatted address from the database. Present for reverse geocode address results.

house_number?: string | null

House or building number. Present for address and interpolated results.

interpolated?: boolean | null

Whether this result was estimated by address interpolation rather than an exact database match.

name?: string | null

Place name (raw). Present for reverse geocode place results.

osm_id?: number | null

OpenStreetMap element ID (null for interpolated results)

osm_type?: "node" | "way" | "relation" | null

OSM element type (node, way, relation)

One of the following:
"node"
"way"
"relation"
postcode?: string | null

Postal code. Present for reverse geocode address results.

score?: number | null

Relevance score (higher is better). Incorporates text match quality, spatial proximity boost, and popularity signals. Not bounded to 0-1.

minimum0
source?: "structured" | "bm25" | "fuzzy" | 3 more | null

Result source indicating how the result was found: structured (exact field match), bm25 (full-text search), fuzzy (trigram similarity), address (reverse geocode address), place (reverse geocode POI), interpolation (estimated from neighboring addresses)

One of the following:
"structured"
"bm25"
"fuzzy"
"address"
"place"
"interpolation"
state?: string | null

State or province name. Present for reverse geocode address results.

street?: string | null

Street name. Present for address and interpolated results.

subcategory?: string | null

POI subcategory. Present for place results.

tags?: Record<string, string> | null

Raw OSM tags. Present for place results.

wikipedia?: string | null

Wikipedia article reference (e.g. en:Eiffel Tower). Present for notable places.

type: "Feature"
type: "FeatureCollection"
GeocodeResult { features, type }

GeoJSON FeatureCollection of forward geocoding results, ordered by relevance. Content-Type: application/geo+json.

features: Array<GeocodingFeature { geometry, properties, type } >

Geocoding results ordered by relevance score

geometry: GeoJsonGeometry { coordinates, type }

GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

coordinates: Array<number> | Array<Array<number>> | Array<Array<Array<number>>> | Array<Array<Array<Array<number>>>>

Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

One of the following:
Array<number>
Array<Array<number>>
Array<Array<Array<number>>>
Array<Array<Array<Array<number>>>>
type: "Point" | "LineString" | "Polygon" | 3 more

Geometry type

One of the following:
"Point"
"LineString"
"Polygon"
"MultiPoint"
"MultiLineString"
"MultiPolygon"
properties: Properties { display_name, category, city, 18 more }

Geocoding result properties

display_name: string

Formatted address or place name

category?: string | null

POI category (e.g. restaurant, cafe, park). Present for place results.

city?: string | null

City or town name. Present for address results.

confidence?: number | null

Interpolation confidence (0-1). Present only for interpolated results.

maximum1
minimum0
country?: string | null

Country name. Present for reverse geocode address results.

country_code?: string | null

ISO 3166-1 alpha-2 country code

maxLength2
minLength2
distance_m?: number | null

Distance from the query point in meters (reverse geocode / nearby only)

full_address?: string | null

Complete formatted address from the database. Present for reverse geocode address results.

house_number?: string | null

House or building number. Present for address and interpolated results.

interpolated?: boolean | null

Whether this result was estimated by address interpolation rather than an exact database match.

name?: string | null

Place name (raw). Present for reverse geocode place results.

osm_id?: number | null

OpenStreetMap element ID (null for interpolated results)

osm_type?: "node" | "way" | "relation" | null

OSM element type (node, way, relation)

One of the following:
"node"
"way"
"relation"
postcode?: string | null

Postal code. Present for reverse geocode address results.

score?: number | null

Relevance score (higher is better). Incorporates text match quality, spatial proximity boost, and popularity signals. Not bounded to 0-1.

minimum0
source?: "structured" | "bm25" | "fuzzy" | 3 more | null

Result source indicating how the result was found: structured (exact field match), bm25 (full-text search), fuzzy (trigram similarity), address (reverse geocode address), place (reverse geocode POI), interpolation (estimated from neighboring addresses)

One of the following:
"structured"
"bm25"
"fuzzy"
"address"
"place"
"interpolation"
state?: string | null

State or province name. Present for reverse geocode address results.

street?: string | null

Street name. Present for address and interpolated results.

subcategory?: string | null

POI subcategory. Present for place results.

tags?: Record<string, string> | null

Raw OSM tags. Present for place results.

wikipedia?: string | null

Wikipedia article reference (e.g. en:Eiffel Tower). Present for notable places.

type: "Feature"
type: "FeatureCollection"
GeocodingFeature { geometry, properties, type }

GeoJSON Feature representing a geocoding result. The geometry is always a Point. Properties include the formatted display name, OSM metadata, confidence score, and source type.

geometry: GeoJsonGeometry { coordinates, type }

GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

coordinates: Array<number> | Array<Array<number>> | Array<Array<Array<number>>> | Array<Array<Array<Array<number>>>>

Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

One of the following:
Array<number>
Array<Array<number>>
Array<Array<Array<number>>>
Array<Array<Array<Array<number>>>>
type: "Point" | "LineString" | "Polygon" | 3 more

Geometry type

One of the following:
"Point"
"LineString"
"Polygon"
"MultiPoint"
"MultiLineString"
"MultiPolygon"
properties: Properties { display_name, category, city, 18 more }

Geocoding result properties

display_name: string

Formatted address or place name

category?: string | null

POI category (e.g. restaurant, cafe, park). Present for place results.

city?: string | null

City or town name. Present for address results.

confidence?: number | null

Interpolation confidence (0-1). Present only for interpolated results.

maximum1
minimum0
country?: string | null

Country name. Present for reverse geocode address results.

country_code?: string | null

ISO 3166-1 alpha-2 country code

maxLength2
minLength2
distance_m?: number | null

Distance from the query point in meters (reverse geocode / nearby only)

full_address?: string | null

Complete formatted address from the database. Present for reverse geocode address results.

house_number?: string | null

House or building number. Present for address and interpolated results.

interpolated?: boolean | null

Whether this result was estimated by address interpolation rather than an exact database match.

name?: string | null

Place name (raw). Present for reverse geocode place results.

osm_id?: number | null

OpenStreetMap element ID (null for interpolated results)

osm_type?: "node" | "way" | "relation" | null

OSM element type (node, way, relation)

One of the following:
"node"
"way"
"relation"
postcode?: string | null

Postal code. Present for reverse geocode address results.

score?: number | null

Relevance score (higher is better). Incorporates text match quality, spatial proximity boost, and popularity signals. Not bounded to 0-1.

minimum0
source?: "structured" | "bm25" | "fuzzy" | 3 more | null

Result source indicating how the result was found: structured (exact field match), bm25 (full-text search), fuzzy (trigram similarity), address (reverse geocode address), place (reverse geocode POI), interpolation (estimated from neighboring addresses)

One of the following:
"structured"
"bm25"
"fuzzy"
"address"
"place"
"interpolation"
state?: string | null

State or province name. Present for reverse geocode address results.

street?: string | null

Street name. Present for address and interpolated results.

subcategory?: string | null

POI subcategory. Present for place results.

tags?: Record<string, string> | null

Raw OSM tags. Present for place results.

wikipedia?: string | null

Wikipedia article reference (e.g. en:Eiffel Tower). Present for notable places.

type: "Feature"
ReverseGeocodeResult { features, type }

GeoJSON FeatureCollection of reverse geocoding results, ordered by distance from the query point. Content-Type: application/geo+json.

features: Array<GeocodingFeature { geometry, properties, type } >

Reverse geocoding results ordered by distance

geometry: GeoJsonGeometry { coordinates, type }

GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

coordinates: Array<number> | Array<Array<number>> | Array<Array<Array<number>>> | Array<Array<Array<Array<number>>>>

Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

One of the following:
Array<number>
Array<Array<number>>
Array<Array<Array<number>>>
Array<Array<Array<Array<number>>>>
type: "Point" | "LineString" | "Polygon" | 3 more

Geometry type

One of the following:
"Point"
"LineString"
"Polygon"
"MultiPoint"
"MultiLineString"
"MultiPolygon"
properties: Properties { display_name, category, city, 18 more }

Geocoding result properties

display_name: string

Formatted address or place name

category?: string | null

POI category (e.g. restaurant, cafe, park). Present for place results.

city?: string | null

City or town name. Present for address results.

confidence?: number | null

Interpolation confidence (0-1). Present only for interpolated results.

maximum1
minimum0
country?: string | null

Country name. Present for reverse geocode address results.

country_code?: string | null

ISO 3166-1 alpha-2 country code

maxLength2
minLength2
distance_m?: number | null

Distance from the query point in meters (reverse geocode / nearby only)

full_address?: string | null

Complete formatted address from the database. Present for reverse geocode address results.

house_number?: string | null

House or building number. Present for address and interpolated results.

interpolated?: boolean | null

Whether this result was estimated by address interpolation rather than an exact database match.

name?: string | null

Place name (raw). Present for reverse geocode place results.

osm_id?: number | null

OpenStreetMap element ID (null for interpolated results)

osm_type?: "node" | "way" | "relation" | null

OSM element type (node, way, relation)

One of the following:
"node"
"way"
"relation"
postcode?: string | null

Postal code. Present for reverse geocode address results.

score?: number | null

Relevance score (higher is better). Incorporates text match quality, spatial proximity boost, and popularity signals. Not bounded to 0-1.

minimum0
source?: "structured" | "bm25" | "fuzzy" | 3 more | null

Result source indicating how the result was found: structured (exact field match), bm25 (full-text search), fuzzy (trigram similarity), address (reverse geocode address), place (reverse geocode POI), interpolation (estimated from neighboring addresses)

One of the following:
"structured"
"bm25"
"fuzzy"
"address"
"place"
"interpolation"
state?: string | null

State or province name. Present for reverse geocode address results.

street?: string | null

Street name. Present for address and interpolated results.

subcategory?: string | null

POI subcategory. Present for place results.

tags?: Record<string, string> | null

Raw OSM tags. Present for place results.

wikipedia?: string | null

Wikipedia article reference (e.g. en:Eiffel Tower). Present for notable places.

type: "Feature"
type: "FeatureCollection"