Skip to content
Plaza Plaza Docs
GuidesBlogPlaygroundDashboard
API Reference

Geocode

Forward geocode an address
geocode.forward(GeocodeForwardParams**kwargs) -> GeocodeResult
GET/api/v1/geocode
Forward geocode an address
geocode.forward_post(GeocodeForwardPostParams**kwargs) -> GeocodeResult
POST/api/v1/geocode
Reverse geocode a coordinate
geocode.reverse(GeocodeReverseParams**kwargs) -> ReverseGeocodeResult
GET/api/v1/geocode/reverse
Reverse geocode a coordinate
geocode.reverse_post(GeocodeReversePostParams**kwargs) -> ReverseGeocodeResult
POST/api/v1/geocode/reverse
Autocomplete a partial address
geocode.autocomplete(GeocodeAutocompleteParams**kwargs) -> AutocompleteResult
GET/api/v1/geocode/autocomplete
Autocomplete a partial address
geocode.autocomplete_post(GeocodeAutocompletePostParams**kwargs) -> AutocompleteResult
POST/api/v1/geocode/autocomplete
Batch geocode multiple addresses
geocode.batch(GeocodeBatchParams**kwargs) -> GeocodeBatchResponse
POST/api/v1/geocode/batch
ModelsExpand Collapse
class AutocompleteResult: …

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

features: List[GeocodingFeature]

Autocomplete suggestions ordered by relevance

geometry: GeoJsonGeometry

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

coordinates: Union[List[float], List[List[float]], List[List[List[float]]], List[List[List[List[float]]]]]

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

One of the following:
List[float]

[longitude, latitude] or [longitude, latitude, elevation]

List[List[float]]

Array of [lng, lat] positions

List[List[List[float]]]

Array of linear rings / line strings

List[List[List[List[float]]]]

Array of polygons

type: Literal["Point", "LineString", "Polygon", 3 more]

Geometry type

One of the following:
"Point"
"LineString"
"Polygon"
"MultiPoint"
"MultiLineString"
"MultiPolygon"
properties: Properties

Geocoding result properties

display_name: str

Formatted address or place name

category: Optional[str]

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

city: Optional[str]

City or town name. Present for address results.

confidence: Optional[float]

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

maximum1
minimum0
country: Optional[str]

Country name. Present for reverse geocode address results.

country_code: Optional[str]

ISO 3166-1 alpha-2 country code

maxLength2
minLength2
distance_m: Optional[float]

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

full_address: Optional[str]

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

house_number: Optional[str]

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

interpolated: Optional[bool]

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

name: Optional[str]

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

osm_id: Optional[int]

OpenStreetMap element ID (null for interpolated results)

osm_type: Optional[Literal["node", "way", "relation"]]

OSM element type (node, way, relation)

One of the following:
"node"
"way"
"relation"
postcode: Optional[str]

Postal code. Present for reverse geocode address results.

score: Optional[float]

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

minimum0
source: Optional[Literal["structured", "bm25", "fuzzy", 3 more]]

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: Optional[str]

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

street: Optional[str]

Street name. Present for address and interpolated results.

subcategory: Optional[str]

POI subcategory. Present for place results.

tags: Optional[Dict[str, str]]

Raw OSM tags. Present for place results.

wikipedia: Optional[str]

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

type: Literal["Feature"]
type: Literal["FeatureCollection"]
class GeocodeResult: …

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

features: List[GeocodingFeature]

Geocoding results ordered by relevance score

geometry: GeoJsonGeometry

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

coordinates: Union[List[float], List[List[float]], List[List[List[float]]], List[List[List[List[float]]]]]

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

One of the following:
List[float]

[longitude, latitude] or [longitude, latitude, elevation]

List[List[float]]

Array of [lng, lat] positions

List[List[List[float]]]

Array of linear rings / line strings

List[List[List[List[float]]]]

Array of polygons

type: Literal["Point", "LineString", "Polygon", 3 more]

Geometry type

One of the following:
"Point"
"LineString"
"Polygon"
"MultiPoint"
"MultiLineString"
"MultiPolygon"
properties: Properties

Geocoding result properties

display_name: str

Formatted address or place name

category: Optional[str]

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

city: Optional[str]

City or town name. Present for address results.

confidence: Optional[float]

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

maximum1
minimum0
country: Optional[str]

Country name. Present for reverse geocode address results.

country_code: Optional[str]

ISO 3166-1 alpha-2 country code

maxLength2
minLength2
distance_m: Optional[float]

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

full_address: Optional[str]

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

house_number: Optional[str]

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

interpolated: Optional[bool]

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

name: Optional[str]

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

osm_id: Optional[int]

OpenStreetMap element ID (null for interpolated results)

osm_type: Optional[Literal["node", "way", "relation"]]

OSM element type (node, way, relation)

One of the following:
"node"
"way"
"relation"
postcode: Optional[str]

Postal code. Present for reverse geocode address results.

score: Optional[float]

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

minimum0
source: Optional[Literal["structured", "bm25", "fuzzy", 3 more]]

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: Optional[str]

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

street: Optional[str]

Street name. Present for address and interpolated results.

subcategory: Optional[str]

POI subcategory. Present for place results.

tags: Optional[Dict[str, str]]

Raw OSM tags. Present for place results.

wikipedia: Optional[str]

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

type: Literal["Feature"]
type: Literal["FeatureCollection"]
class GeocodingFeature: …

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

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

coordinates: Union[List[float], List[List[float]], List[List[List[float]]], List[List[List[List[float]]]]]

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

One of the following:
List[float]

[longitude, latitude] or [longitude, latitude, elevation]

List[List[float]]

Array of [lng, lat] positions

List[List[List[float]]]

Array of linear rings / line strings

List[List[List[List[float]]]]

Array of polygons

type: Literal["Point", "LineString", "Polygon", 3 more]

Geometry type

One of the following:
"Point"
"LineString"
"Polygon"
"MultiPoint"
"MultiLineString"
"MultiPolygon"
properties: Properties

Geocoding result properties

display_name: str

Formatted address or place name

category: Optional[str]

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

city: Optional[str]

City or town name. Present for address results.

confidence: Optional[float]

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

maximum1
minimum0
country: Optional[str]

Country name. Present for reverse geocode address results.

country_code: Optional[str]

ISO 3166-1 alpha-2 country code

maxLength2
minLength2
distance_m: Optional[float]

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

full_address: Optional[str]

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

house_number: Optional[str]

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

interpolated: Optional[bool]

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

name: Optional[str]

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

osm_id: Optional[int]

OpenStreetMap element ID (null for interpolated results)

osm_type: Optional[Literal["node", "way", "relation"]]

OSM element type (node, way, relation)

One of the following:
"node"
"way"
"relation"
postcode: Optional[str]

Postal code. Present for reverse geocode address results.

score: Optional[float]

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

minimum0
source: Optional[Literal["structured", "bm25", "fuzzy", 3 more]]

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: Optional[str]

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

street: Optional[str]

Street name. Present for address and interpolated results.

subcategory: Optional[str]

POI subcategory. Present for place results.

tags: Optional[Dict[str, str]]

Raw OSM tags. Present for place results.

wikipedia: Optional[str]

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

type: Literal["Feature"]
class ReverseGeocodeResult: …

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

features: List[GeocodingFeature]

Reverse geocoding results ordered by distance

geometry: GeoJsonGeometry

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

coordinates: Union[List[float], List[List[float]], List[List[List[float]]], List[List[List[List[float]]]]]

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

One of the following:
List[float]

[longitude, latitude] or [longitude, latitude, elevation]

List[List[float]]

Array of [lng, lat] positions

List[List[List[float]]]

Array of linear rings / line strings

List[List[List[List[float]]]]

Array of polygons

type: Literal["Point", "LineString", "Polygon", 3 more]

Geometry type

One of the following:
"Point"
"LineString"
"Polygon"
"MultiPoint"
"MultiLineString"
"MultiPolygon"
properties: Properties

Geocoding result properties

display_name: str

Formatted address or place name

category: Optional[str]

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

city: Optional[str]

City or town name. Present for address results.

confidence: Optional[float]

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

maximum1
minimum0
country: Optional[str]

Country name. Present for reverse geocode address results.

country_code: Optional[str]

ISO 3166-1 alpha-2 country code

maxLength2
minLength2
distance_m: Optional[float]

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

full_address: Optional[str]

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

house_number: Optional[str]

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

interpolated: Optional[bool]

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

name: Optional[str]

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

osm_id: Optional[int]

OpenStreetMap element ID (null for interpolated results)

osm_type: Optional[Literal["node", "way", "relation"]]

OSM element type (node, way, relation)

One of the following:
"node"
"way"
"relation"
postcode: Optional[str]

Postal code. Present for reverse geocode address results.

score: Optional[float]

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

minimum0
source: Optional[Literal["structured", "bm25", "fuzzy", 3 more]]

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: Optional[str]

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

street: Optional[str]

Street name. Present for address and interpolated results.

subcategory: Optional[str]

POI subcategory. Present for place results.

tags: Optional[Dict[str, str]]

Raw OSM tags. Present for place results.

wikipedia: Optional[str]

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

type: Literal["Feature"]
type: Literal["FeatureCollection"]