Skip to content
Plaza Plaza Docs
GuidesBlogPlaygroundDashboard
API Reference
Geocode

Forward geocode an address

geocode.forward_post(**kwargs) -> GeocodeResult { features, type }
POST/api/v1/geocode

Forward geocode an address

ParametersExpand Collapse
q: String

Address or place name

bbox: String

Bounding box filter: south,west,north,east

country_code: String

ISO 3166-1 alpha-2 country code filter

format_: String

Response format: json (default), geojson, csv, ndjson

lang: String

Language code for localized names (e.g. en, de, fr)

lat: Float

Focus latitude

layer: String

Filter by layer: address, poi, or admin

limit: Integer

Maximum results (default 20, max 100)

lng: Float

Focus longitude

ReturnsExpand Collapse
class 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[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]

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

One of the following:
Array[Float]

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

Array[Array[Float]]

Array of [lng, lat] positions

Array[Array[Array[Float]]]

Array of linear rings / line strings

Array[Array[Array[Array[Float]]]]

Array of polygons

type: :Point | :LineString | :Polygon | 3 more

Geometry type

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

Geocoding result properties

display_name: String

Formatted address or place name

category: String

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

city: String

City or town name. Present for address results.

confidence: Float

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

maximum1
minimum0
country: String

Country name. Present for reverse geocode address results.

country_code: String

ISO 3166-1 alpha-2 country code

maxLength2
minLength2
distance_m: Float

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

full_address: String

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

house_number: String

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

interpolated: bool

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

name: String

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

osm_id: Integer

OpenStreetMap element ID (null for interpolated results)

osm_type: :node | :way | :relation

OSM element type (node, way, relation)

One of the following:
:node
:way
:relation
postcode: String

Postal code. Present for reverse geocode address results.

score: Float

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

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

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

street: String

Street name. Present for address and interpolated results.

subcategory: String

POI subcategory. Present for place results.

tags: Hash[Symbol, String]

Raw OSM tags. Present for place results.

wikipedia: String

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

type: :Feature
type: :FeatureCollection

Forward geocode an address

require "plaza"

plaza = Plaza::Client.new(
  api_key: "My API Key",
  environment: "local" # defaults to "production"
)

geocode_result = plaza.geocode.forward_post(q: "q")

puts(geocode_result)
{
  "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"
}
Returns Examples
{
  "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"
}