## Forward geocode an address

`geocode().forwardPost(GeocodeForwardPostParamsparams, RequestOptionsrequestOptions = RequestOptions.none()) : GeocodeResult`

**post** `/api/v1/geocode`

Forward geocode an address

### Parameters

- `params: GeocodeForwardPostParams`

  - `q: String`

    Address or place name

  - `bbox: Optional<String>`

    Bounding box filter: south,west,north,east

  - `countryCode: Optional<String>`

    ISO 3166-1 alpha-2 country code filter

  - `format: Optional<String>`

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

  - `lang: Optional<String>`

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

  - `lat: Optional<Double>`

    Focus latitude

  - `layer: Optional<String>`

    Filter by layer: address, poi, or admin

  - `limit: Optional<Long>`

    Maximum results (default 20, max 100)

  - `lng: Optional<Double>`

    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: Coordinates`

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

        - `List<Double>`

        - `List<List<Double>>`

        - `List<List<List<Double>>>`

        - `List<List<List<List<Double>>>>`

      - `type: Type`

        Geometry type

        - `POINT("Point")`

        - `LINE_STRING("LineString")`

        - `POLYGON("Polygon")`

        - `MULTI_POINT("MultiPoint")`

        - `MULTI_LINE_STRING("MultiLineString")`

        - `MULTI_POLYGON("MultiPolygon")`

    - `properties: Properties`

      Geocoding result properties

      - `displayName: String`

        Formatted address or place name

      - `category: Optional<String>`

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

      - `city: Optional<String>`

        City or town name. Present for address results.

      - `confidence: Optional<Double>`

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

      - `country: Optional<String>`

        Country name. Present for reverse geocode address results.

      - `countryCode: Optional<String>`

        ISO 3166-1 alpha-2 country code

      - `distanceM: Optional<Double>`

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

      - `fullAddress: Optional<String>`

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

      - `houseNumber: Optional<String>`

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

      - `interpolated: Optional<Boolean>`

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

      - `name: Optional<String>`

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

      - `osmId: Optional<Long>`

        OpenStreetMap element ID (null for interpolated results)

      - `osmType: Optional<OsmType>`

        OSM element type (node, way, relation)

        - `NODE("node")`

        - `WAY("way")`

        - `RELATION("relation")`

      - `postcode: Optional<String>`

        Postal code. Present for reverse geocode address results.

      - `score: Optional<Double>`

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

      - `source: Optional<Source>`

        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("structured")`

        - `BM25("bm25")`

        - `FUZZY("fuzzy")`

        - `ADDRESS("address")`

        - `PLACE("place")`

        - `INTERPOLATION("interpolation")`

      - `state: Optional<String>`

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

      - `street: Optional<String>`

        Street name. Present for address and interpolated results.

      - `subcategory: Optional<String>`

        POI subcategory. Present for place results.

      - `tags: Optional<Tags>`

        Raw OSM tags. Present for place results.

      - `wikipedia: Optional<String>`

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

    - `type: Type`

      - `FEATURE("Feature")`

  - `type: Type`

    - `FEATURE_COLLECTION("FeatureCollection")`

### Example

```kotlin
package com.plazafyi.example

import com.plazafyi.client.PlazaClient
import com.plazafyi.client.okhttp.PlazaOkHttpClient
import com.plazafyi.models.geocode.GeocodeForwardPostParams
import com.plazafyi.models.geocode.GeocodeResult

fun main() {
    val client: PlazaClient = PlazaOkHttpClient.fromEnv()

    val params: GeocodeForwardPostParams = GeocodeForwardPostParams.builder()
        .q("q")
        .build()
    val geocodeResult: GeocodeResult = client.geocode().forwardPost(params)
}
```

#### 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"
}
```