# Geocode

## Forward geocode an address

`$client->geocode->forward(string q, ?string bbox, ?string countryCode, ?string lang, ?float lat, ?string layer, ?int limit, ?float lng): GeocodeResult`

**get** `/api/v1/geocode`

Forward geocode an address

### Parameters

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

- `lang?:optional string`

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

- `lat?:optional float`

  Focus latitude

- `layer?:optional string`

  Filter by layer: address, poi, or admin

- `limit?:optional int`

  Maximum results (default 20, max 100)

- `lng?:optional float`

  Focus longitude

### Returns

- `GeocodeResult`

  - `list<GeocodingFeature> features`

    Geocoding results ordered by relevance score

  - `Type type`

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(apiKey: 'My API Key', environment: 'local');

$geocodeResult = $client->geocode->forward(
  q: 'q',
  bbox: 'bbox',
  countryCode: 'country_code',
  lang: 'lang',
  lat: 0,
  layer: 'layer',
  limit: 0,
  lng: 0,
);

var_dump($geocodeResult);
```

#### 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

`$client->geocode->forwardPost(string q, ?string bbox, ?string countryCode, ?string lang, ?float lat, ?string layer, ?int limit, ?float lng): GeocodeResult`

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

Forward geocode an address

### Parameters

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

- `lang?:optional string`

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

- `lat?:optional float`

  Focus latitude

- `layer?:optional string`

  Filter by layer: address, poi, or admin

- `limit?:optional int`

  Maximum results (default 20, max 100)

- `lng?:optional float`

  Focus longitude

### Returns

- `GeocodeResult`

  - `list<GeocodingFeature> features`

    Geocoding results ordered by relevance score

  - `Type type`

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(apiKey: 'My API Key', environment: 'local');

$geocodeResult = $client->geocode->forwardPost(
  q: 'q',
  bbox: 'bbox',
  countryCode: 'country_code',
  lang: 'lang',
  lat: 0,
  layer: 'layer',
  limit: 0,
  lng: 0,
);

var_dump($geocodeResult);
```

#### 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

`$client->geocode->reverse(?string lang, ?float lat, ?string layer, ?int limit, ?float lng, ?string near, ?int radius): ReverseGeocodeResult`

**get** `/api/v1/geocode/reverse`

Reverse geocode a coordinate

### Parameters

- `lang?:optional string`

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

- `lat?:optional float`

  Legacy shorthand. Latitude. Use near param instead.

- `layer?:optional string`

  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 string`

  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

- `ReverseGeocodeResult`

  - `list<GeocodingFeature> features`

    Reverse geocoding results ordered by distance

  - `Type type`

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(apiKey: 'My API Key', environment: 'local');

$reverseGeocodeResult = $client->geocode->reverse(
  lang: 'lang',
  lat: 0,
  layer: 'layer',
  limit: 0,
  lng: 0,
  near: 'near',
  radius: 0,
);

var_dump($reverseGeocodeResult);
```

#### 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

`$client->geocode->reversePost(?string lang, ?float lat, ?string layer, ?int limit, ?float lng, ?string near, ?int radius): ReverseGeocodeResult`

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

Reverse geocode a coordinate

### Parameters

- `lang?:optional string`

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

- `lat?:optional float`

  Legacy shorthand. Latitude. Use near param instead.

- `layer?:optional string`

  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 string`

  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

- `ReverseGeocodeResult`

  - `list<GeocodingFeature> features`

    Reverse geocoding results ordered by distance

  - `Type type`

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(apiKey: 'My API Key', environment: 'local');

$reverseGeocodeResult = $client->geocode->reversePost(
  lang: 'lang',
  lat: 0,
  layer: 'layer',
  limit: 0,
  lng: 0,
  near: 'near',
  radius: 0,
);

var_dump($reverseGeocodeResult);
```

#### 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

`$client->geocode->autocomplete(string q, ?string countryCode, ?string lang, ?float lat, ?string layer, ?int limit, ?float lng): AutocompleteResult`

**get** `/api/v1/geocode/autocomplete`

Autocomplete a partial address

### Parameters

- `q: string`

  Partial address query

- `countryCode?:optional string`

  ISO 3166-1 alpha-2 country code filter

- `lang?:optional string`

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

- `lat?:optional float`

  Focus latitude

- `layer?:optional string`

  Filter by layer: address, poi, or admin

- `limit?:optional int`

  Maximum results (default 10, max 20)

- `lng?:optional float`

  Focus longitude

### Returns

- `AutocompleteResult`

  - `list<GeocodingFeature> features`

    Autocomplete suggestions ordered by relevance

  - `Type type`

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(apiKey: 'My API Key', environment: 'local');

$autocompleteResult = $client->geocode->autocomplete(
  q: 'q',
  countryCode: 'country_code',
  lang: 'lang',
  lat: 0,
  layer: 'layer',
  limit: 0,
  lng: 0,
);

var_dump($autocompleteResult);
```

#### 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

`$client->geocode->autocompletePost(string q, ?string countryCode, ?string lang, ?float lat, ?string layer, ?int limit, ?float lng): AutocompleteResult`

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

Autocomplete a partial address

### Parameters

- `q: string`

  Partial address query

- `countryCode?:optional string`

  ISO 3166-1 alpha-2 country code filter

- `lang?:optional string`

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

- `lat?:optional float`

  Focus latitude

- `layer?:optional string`

  Filter by layer: address, poi, or admin

- `limit?:optional int`

  Maximum results (default 10, max 20)

- `lng?:optional float`

  Focus longitude

### Returns

- `AutocompleteResult`

  - `list<GeocodingFeature> features`

    Autocomplete suggestions ordered by relevance

  - `Type type`

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(apiKey: 'My API Key', environment: 'local');

$autocompleteResult = $client->geocode->autocompletePost(
  q: 'q',
  countryCode: 'country_code',
  lang: 'lang',
  lat: 0,
  layer: 'layer',
  limit: 0,
  lng: 0,
);

var_dump($autocompleteResult);
```

#### 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

`$client->geocode->batch(list<string> addresses): GeocodeBatchResponse`

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

Batch geocode multiple addresses

### Parameters

- `addresses: list<string>`

### Returns

- `GeocodeBatchResponse`

  - `int count`

    Number of addresses processed (always equals length of results)

  - `list<GeocodeResult> results`

    Array of FeatureCollections, one per input address. Empty FeatureCollections indicate no match.

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(apiKey: 'My API Key', environment: 'local');

$response = $client->geocode->batch(addresses: ['string']);

var_dump($response);
```

#### 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

- `AutocompleteResult`

  - `list<GeocodingFeature> features`

    Autocomplete suggestions ordered by relevance

  - `Type type`

### Geocode Result

- `GeocodeResult`

  - `list<GeocodingFeature> features`

    Geocoding results ordered by relevance score

  - `Type type`

### Geocoding Feature

- `GeocodingFeature`

  - `GeoJsonGeometry geometry`

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

  - `Properties properties`

    Geocoding result properties

  - `Type type`

### Reverse Geocode Result

- `ReverseGeocodeResult`

  - `list<GeocodingFeature> features`

    Reverse geocoding results ordered by distance

  - `Type type`