API Reference

Geocode

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Forward geocode an address

client.Geocode.Forward(ctx, query) (*GeocodeResult, error)

GET/api/v1/geocode

Forward geocode an address

ParametersExpand Collapse

query GeocodeForwardParams

Q param.Field[string]

Address or place name

Bbox param.Field[string]optional

Bounding box filter: south,west,north,east

CountryCode param.Field[string]optional

ISO 3166-1 alpha-2 country code filter

Format param.Field[string]optional

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

Lang param.Field[string]optional

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

Lat param.Field[float64]optional

Focus latitude

Layer param.Field[string]optional

Filter by layer: address, poi, or admin

Limit param.Field[int64]optional

Maximum results (default 20, max 100)

Lng param.Field[float64]optional

Focus longitude

ReturnsExpand Collapse

type GeocodeResult struct{…}

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

Features []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 GeoJsonGeometryCoordinatesUnion

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

One of the following:

type GeoJsonGeometryCoordinatesPoint []float64

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

type GeoJsonGeometryCoordinatesLineStringOrMultiPoint [][]float64

Array of [lng, lat] positions

type GeoJsonGeometryCoordinatesPolygonOrMultiLineString [][][]float64

Array of linear rings / line strings

type GeoJsonGeometryCoordinatesMultiPolygon [][][][]float64

Array of polygons

Type GeoJsonGeometryType

Geometry type

One of the following:

const GeoJsonGeometryTypePoint GeoJsonGeometryType = "Point"

const GeoJsonGeometryTypeLineString GeoJsonGeometryType = "LineString"

const GeoJsonGeometryTypePolygon GeoJsonGeometryType = "Polygon"

const GeoJsonGeometryTypeMultiPoint GeoJsonGeometryType = "MultiPoint"

const GeoJsonGeometryTypeMultiLineString GeoJsonGeometryType = "MultiLineString"

const GeoJsonGeometryTypeMultiPolygon GeoJsonGeometryType = "MultiPolygon"

Properties GeocodingFeatureProperties

Geocoding result properties

DisplayName string

Formatted address or place name

Category stringoptional

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

City stringoptional

City or town name. Present for address results.

Confidence float64optional

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

maximum1

minimum0

Country stringoptional

Country name. Present for reverse geocode address results.

CountryCode stringoptional

ISO 3166-1 alpha-2 country code

maxLength2

minLength2

DistanceM float64optional

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

FullAddress stringoptional

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

HouseNumber stringoptional

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

Interpolated booloptional

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

Name stringoptional

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

OsmID int64optional

OpenStreetMap element ID (null for interpolated results)

OsmType GeocodingFeaturePropertiesOsmTypeoptional

OSM element type (node, way, relation)

One of the following:

const GeocodingFeaturePropertiesOsmTypeNode GeocodingFeaturePropertiesOsmType = "node"

const GeocodingFeaturePropertiesOsmTypeWay GeocodingFeaturePropertiesOsmType = "way"

const GeocodingFeaturePropertiesOsmTypeRelation GeocodingFeaturePropertiesOsmType = "relation"

Postcode stringoptional

Postal code. Present for reverse geocode address results.

Score float64optional

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

minimum0

Source GeocodingFeaturePropertiesSourceoptional

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:

const GeocodingFeaturePropertiesSourceStructured GeocodingFeaturePropertiesSource = "structured"

const GeocodingFeaturePropertiesSourceBm25 GeocodingFeaturePropertiesSource = "bm25"

const GeocodingFeaturePropertiesSourceFuzzy GeocodingFeaturePropertiesSource = "fuzzy"

const GeocodingFeaturePropertiesSourceAddress GeocodingFeaturePropertiesSource = "address"

const GeocodingFeaturePropertiesSourcePlace GeocodingFeaturePropertiesSource = "place"

const GeocodingFeaturePropertiesSourceInterpolation GeocodingFeaturePropertiesSource = "interpolation"

State stringoptional

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

Street stringoptional

Street name. Present for address and interpolated results.

Subcategory stringoptional

POI subcategory. Present for place results.

Tags map[string, string]optional

Raw OSM tags. Present for place results.

Wikipedia stringoptional

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

Type GeocodingFeatureType

Type GeocodeResultType

Forward geocode an address

Go

HTTP

TypeScript

Python

Java

Kotlin

Go

Ruby

CLI Tool

PHP

C#

package main

import (
  "context"
  "fmt"

  "github.com/plazafyi/plaza-go"
  "github.com/plazafyi/plaza-go/option"
)

func main() {
  client := githubcomplazafyiplazago.NewClient(
    option.WithAPIKey("My API Key"),
  )
  geocodeResult, err := client.Geocode.Forward(context.TODO(), githubcomplazafyiplazago.GeocodeForwardParams{
    Q: githubcomplazafyiplazago.F("q"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", geocodeResult.Features)
}

200 example

{
  "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

200 example

{
  "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"
}