# Geocode ## Forward geocode an address `geocode.forward(GeocodeForwardParams**kwargs) -> GeocodeResult` **get** `/api/v1/geocode` Forward geocode an address ### Parameters - `q: str` Address or place name - `bbox: Optional[str]` Bounding box filter: south,west,north,east - `country_code: Optional[str]` ISO 3166-1 alpha-2 country code filter - `lang: Optional[str]` Language code for localized names (e.g. en, de, fr) - `lat: Optional[float]` Focus latitude - `layer: Optional[str]` Filter by layer: address, poi, or admin - `limit: Optional[int]` Maximum results (default 20, max 100) - `lng: Optional[float]` Focus longitude ### Returns - `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. - `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 - `"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. - `country: Optional[str]` Country name. Present for reverse geocode address results. - `country_code: Optional[str]` ISO 3166-1 alpha-2 country code - `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) - `"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. - `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) - `"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"]` - `"Feature"` - `type: Literal["FeatureCollection"]` - `"FeatureCollection"` ### Example ```python import os from plaza import Plaza client = Plaza( api_key=os.environ.get("PLAZA_API_KEY"), # This is the default and can be omitted ) geocode_result = client.geocode.forward( q="q", ) print(geocode_result.features) ``` #### Response ```json { "features": [ { "geometry": { "coordinates": [ 2.3522, 48.8566 ], "type": "Point" }, "properties": { "display_name": "221B Baker Street, London, NW1 6XE, United Kingdom", "category": "restaurant", "city": "London", "confidence": 0, "country": "United Kingdom", "country_code": "GB", "distance_m": 0, "full_address": "221B Baker Street, London, NW1 6XE, United Kingdom", "house_number": "221B", "interpolated": true, "name": "Eiffel Tower", "osm_id": 21154906, "osm_type": "node", "postcode": "NW1 6XE", "score": 0, "source": "structured", "state": "England", "street": "Baker Street", "subcategory": "italian", "tags": { "foo": "string" }, "wikipedia": "en:Eiffel Tower" }, "type": "Feature" } ], "type": "FeatureCollection" } ``` ## Forward geocode an address `geocode.forward_post(GeocodeForwardPostParams**kwargs) -> GeocodeResult` **post** `/api/v1/geocode` Forward geocode an address ### Parameters - `q: str` Address or place name - `bbox: Optional[str]` Bounding box filter: south,west,north,east - `country_code: Optional[str]` ISO 3166-1 alpha-2 country code filter - `lang: Optional[str]` Language code for localized names (e.g. en, de, fr) - `lat: Optional[float]` Focus latitude - `layer: Optional[str]` Filter by layer: address, poi, or admin - `limit: Optional[int]` Maximum results (default 20, max 100) - `lng: Optional[float]` Focus longitude ### Returns - `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. - `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 - `"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. - `country: Optional[str]` Country name. Present for reverse geocode address results. - `country_code: Optional[str]` ISO 3166-1 alpha-2 country code - `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) - `"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. - `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) - `"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"]` - `"Feature"` - `type: Literal["FeatureCollection"]` - `"FeatureCollection"` ### Example ```python import os from plaza import Plaza client = Plaza( api_key=os.environ.get("PLAZA_API_KEY"), # This is the default and can be omitted ) geocode_result = client.geocode.forward_post( q="q", ) print(geocode_result.features) ``` #### Response ```json { "features": [ { "geometry": { "coordinates": [ 2.3522, 48.8566 ], "type": "Point" }, "properties": { "display_name": "221B Baker Street, London, NW1 6XE, United Kingdom", "category": "restaurant", "city": "London", "confidence": 0, "country": "United Kingdom", "country_code": "GB", "distance_m": 0, "full_address": "221B Baker Street, London, NW1 6XE, United Kingdom", "house_number": "221B", "interpolated": true, "name": "Eiffel Tower", "osm_id": 21154906, "osm_type": "node", "postcode": "NW1 6XE", "score": 0, "source": "structured", "state": "England", "street": "Baker Street", "subcategory": "italian", "tags": { "foo": "string" }, "wikipedia": "en:Eiffel Tower" }, "type": "Feature" } ], "type": "FeatureCollection" } ``` ## Reverse geocode a coordinate `geocode.reverse(GeocodeReverseParams**kwargs) -> ReverseGeocodeResult` **get** `/api/v1/geocode/reverse` Reverse geocode a coordinate ### Parameters - `lang: Optional[str]` Language code for localized names (e.g. en, de, fr) - `lat: Optional[float]` Legacy shorthand. Latitude. Use near param instead. - `layer: Optional[str]` Filter by layer: house or poi - `limit: Optional[int]` Maximum results (default 1, max 20) - `lng: Optional[float]` Legacy shorthand. Longitude. Use near param instead. - `near: Optional[str]` Point geometry for reverse geocode (lat,lng or GeoJSON). Alternative to lat/lng params. - `radius: Optional[int]` Search radius in meters (default 200, max 5000) ### Returns - `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. - `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 - `"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. - `country: Optional[str]` Country name. Present for reverse geocode address results. - `country_code: Optional[str]` ISO 3166-1 alpha-2 country code - `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) - `"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. - `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) - `"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"]` - `"Feature"` - `type: Literal["FeatureCollection"]` - `"FeatureCollection"` ### Example ```python import os from plaza import Plaza client = Plaza( api_key=os.environ.get("PLAZA_API_KEY"), # This is the default and can be omitted ) reverse_geocode_result = client.geocode.reverse() print(reverse_geocode_result.features) ``` #### Response ```json { "features": [ { "geometry": { "coordinates": [ 2.3522, 48.8566 ], "type": "Point" }, "properties": { "display_name": "221B Baker Street, London, NW1 6XE, United Kingdom", "category": "restaurant", "city": "London", "confidence": 0, "country": "United Kingdom", "country_code": "GB", "distance_m": 0, "full_address": "221B Baker Street, London, NW1 6XE, United Kingdom", "house_number": "221B", "interpolated": true, "name": "Eiffel Tower", "osm_id": 21154906, "osm_type": "node", "postcode": "NW1 6XE", "score": 0, "source": "structured", "state": "England", "street": "Baker Street", "subcategory": "italian", "tags": { "foo": "string" }, "wikipedia": "en:Eiffel Tower" }, "type": "Feature" } ], "type": "FeatureCollection" } ``` ## Reverse geocode a coordinate `geocode.reverse_post(GeocodeReversePostParams**kwargs) -> ReverseGeocodeResult` **post** `/api/v1/geocode/reverse` Reverse geocode a coordinate ### Parameters - `lang: Optional[str]` Language code for localized names (e.g. en, de, fr) - `lat: Optional[float]` Legacy shorthand. Latitude. Use near param instead. - `layer: Optional[str]` Filter by layer: house or poi - `limit: Optional[int]` Maximum results (default 1, max 20) - `lng: Optional[float]` Legacy shorthand. Longitude. Use near param instead. - `near: Optional[str]` Point geometry for reverse geocode (lat,lng or GeoJSON). Alternative to lat/lng params. - `radius: Optional[int]` Search radius in meters (default 200, max 5000) ### Returns - `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. - `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 - `"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. - `country: Optional[str]` Country name. Present for reverse geocode address results. - `country_code: Optional[str]` ISO 3166-1 alpha-2 country code - `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) - `"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. - `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) - `"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"]` - `"Feature"` - `type: Literal["FeatureCollection"]` - `"FeatureCollection"` ### Example ```python import os from plaza import Plaza client = Plaza( api_key=os.environ.get("PLAZA_API_KEY"), # This is the default and can be omitted ) reverse_geocode_result = client.geocode.reverse_post() print(reverse_geocode_result.features) ``` #### Response ```json { "features": [ { "geometry": { "coordinates": [ 2.3522, 48.8566 ], "type": "Point" }, "properties": { "display_name": "221B Baker Street, London, NW1 6XE, United Kingdom", "category": "restaurant", "city": "London", "confidence": 0, "country": "United Kingdom", "country_code": "GB", "distance_m": 0, "full_address": "221B Baker Street, London, NW1 6XE, United Kingdom", "house_number": "221B", "interpolated": true, "name": "Eiffel Tower", "osm_id": 21154906, "osm_type": "node", "postcode": "NW1 6XE", "score": 0, "source": "structured", "state": "England", "street": "Baker Street", "subcategory": "italian", "tags": { "foo": "string" }, "wikipedia": "en:Eiffel Tower" }, "type": "Feature" } ], "type": "FeatureCollection" } ``` ## Autocomplete a partial address `geocode.autocomplete(GeocodeAutocompleteParams**kwargs) -> AutocompleteResult` **get** `/api/v1/geocode/autocomplete` Autocomplete a partial address ### Parameters - `q: str` Partial address query - `country_code: Optional[str]` ISO 3166-1 alpha-2 country code filter - `lang: Optional[str]` Language code for localized names (e.g. en, de, fr) - `lat: Optional[float]` Focus latitude - `layer: Optional[str]` Filter by layer: address, poi, or admin - `limit: Optional[int]` Maximum results (default 10, max 20) - `lng: Optional[float]` Focus longitude ### Returns - `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. - `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 - `"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. - `country: Optional[str]` Country name. Present for reverse geocode address results. - `country_code: Optional[str]` ISO 3166-1 alpha-2 country code - `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) - `"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. - `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) - `"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"]` - `"Feature"` - `type: Literal["FeatureCollection"]` - `"FeatureCollection"` ### Example ```python import os from plaza import Plaza client = Plaza( api_key=os.environ.get("PLAZA_API_KEY"), # This is the default and can be omitted ) autocomplete_result = client.geocode.autocomplete( q="q", ) print(autocomplete_result.features) ``` #### Response ```json { "features": [ { "geometry": { "coordinates": [ 2.3522, 48.8566 ], "type": "Point" }, "properties": { "display_name": "221B Baker Street, London, NW1 6XE, United Kingdom", "category": "restaurant", "city": "London", "confidence": 0, "country": "United Kingdom", "country_code": "GB", "distance_m": 0, "full_address": "221B Baker Street, London, NW1 6XE, United Kingdom", "house_number": "221B", "interpolated": true, "name": "Eiffel Tower", "osm_id": 21154906, "osm_type": "node", "postcode": "NW1 6XE", "score": 0, "source": "structured", "state": "England", "street": "Baker Street", "subcategory": "italian", "tags": { "foo": "string" }, "wikipedia": "en:Eiffel Tower" }, "type": "Feature" } ], "type": "FeatureCollection" } ``` ## Autocomplete a partial address `geocode.autocomplete_post(GeocodeAutocompletePostParams**kwargs) -> AutocompleteResult` **post** `/api/v1/geocode/autocomplete` Autocomplete a partial address ### Parameters - `q: str` Partial address query - `country_code: Optional[str]` ISO 3166-1 alpha-2 country code filter - `lang: Optional[str]` Language code for localized names (e.g. en, de, fr) - `lat: Optional[float]` Focus latitude - `layer: Optional[str]` Filter by layer: address, poi, or admin - `limit: Optional[int]` Maximum results (default 10, max 20) - `lng: Optional[float]` Focus longitude ### Returns - `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. - `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 - `"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. - `country: Optional[str]` Country name. Present for reverse geocode address results. - `country_code: Optional[str]` ISO 3166-1 alpha-2 country code - `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) - `"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. - `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) - `"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"]` - `"Feature"` - `type: Literal["FeatureCollection"]` - `"FeatureCollection"` ### Example ```python import os from plaza import Plaza client = Plaza( api_key=os.environ.get("PLAZA_API_KEY"), # This is the default and can be omitted ) autocomplete_result = client.geocode.autocomplete_post( q="q", ) print(autocomplete_result.features) ``` #### Response ```json { "features": [ { "geometry": { "coordinates": [ 2.3522, 48.8566 ], "type": "Point" }, "properties": { "display_name": "221B Baker Street, London, NW1 6XE, United Kingdom", "category": "restaurant", "city": "London", "confidence": 0, "country": "United Kingdom", "country_code": "GB", "distance_m": 0, "full_address": "221B Baker Street, London, NW1 6XE, United Kingdom", "house_number": "221B", "interpolated": true, "name": "Eiffel Tower", "osm_id": 21154906, "osm_type": "node", "postcode": "NW1 6XE", "score": 0, "source": "structured", "state": "England", "street": "Baker Street", "subcategory": "italian", "tags": { "foo": "string" }, "wikipedia": "en:Eiffel Tower" }, "type": "Feature" } ], "type": "FeatureCollection" } ``` ## Batch geocode multiple addresses `geocode.batch(GeocodeBatchParams**kwargs) -> GeocodeBatchResponse` **post** `/api/v1/geocode/batch` Batch geocode multiple addresses ### Parameters - `addresses: SequenceNotStr[str]` ### Returns - `class GeocodeBatchResponse: …` Batch geocoding result. Each entry in `results` is a FeatureCollection corresponding to the input address at the same index. Order is preserved. - `count: int` Number of addresses processed (always equals length of results) - `results: List[GeocodeResult]` Array of FeatureCollections, one per input address. Empty FeatureCollections indicate no match. - `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. - `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 - `"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. - `country: Optional[str]` Country name. Present for reverse geocode address results. - `country_code: Optional[str]` ISO 3166-1 alpha-2 country code - `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) - `"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. - `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) - `"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"]` - `"Feature"` - `type: Literal["FeatureCollection"]` - `"FeatureCollection"` ### Example ```python import os from plaza import Plaza client = Plaza( api_key=os.environ.get("PLAZA_API_KEY"), # This is the default and can be omitted ) response = client.geocode.batch( addresses=["string"], ) print(response.count) ``` #### Response ```json { "count": 0, "results": [ { "features": [ { "geometry": { "coordinates": [ 2.3522, 48.8566 ], "type": "Point" }, "properties": { "display_name": "221B Baker Street, London, NW1 6XE, United Kingdom", "category": "restaurant", "city": "London", "confidence": 0, "country": "United Kingdom", "country_code": "GB", "distance_m": 0, "full_address": "221B Baker Street, London, NW1 6XE, United Kingdom", "house_number": "221B", "interpolated": true, "name": "Eiffel Tower", "osm_id": 21154906, "osm_type": "node", "postcode": "NW1 6XE", "score": 0, "source": "structured", "state": "England", "street": "Baker Street", "subcategory": "italian", "tags": { "foo": "string" }, "wikipedia": "en:Eiffel Tower" }, "type": "Feature" } ], "type": "FeatureCollection" } ] } ``` ## Domain Types ### Autocomplete Result - `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. - `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 - `"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. - `country: Optional[str]` Country name. Present for reverse geocode address results. - `country_code: Optional[str]` ISO 3166-1 alpha-2 country code - `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) - `"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. - `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) - `"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"]` - `"Feature"` - `type: Literal["FeatureCollection"]` - `"FeatureCollection"` ### Geocode Result - `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. - `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 - `"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. - `country: Optional[str]` Country name. Present for reverse geocode address results. - `country_code: Optional[str]` ISO 3166-1 alpha-2 country code - `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) - `"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. - `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) - `"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"]` - `"Feature"` - `type: Literal["FeatureCollection"]` - `"FeatureCollection"` ### Geocoding Feature - `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. - `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 - `"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. - `country: Optional[str]` Country name. Present for reverse geocode address results. - `country_code: Optional[str]` ISO 3166-1 alpha-2 country code - `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) - `"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. - `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) - `"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"]` - `"Feature"` ### Reverse Geocode Result - `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. - `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 - `"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. - `country: Optional[str]` Country name. Present for reverse geocode address results. - `country_code: Optional[str]` ISO 3166-1 alpha-2 country code - `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) - `"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. - `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) - `"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"]` - `"Feature"` - `type: Literal["FeatureCollection"]` - `"FeatureCollection"`