> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Geokeo API reference

> API reference for the Geokeo plugin in Corsair: every `geokeo.api.*` operation with its input and output types, taken from the plugin's Zod schemas.

> [!NOTE]
>
> **New to Corsair?** See [API access](https://docs.corsair.dev/concepts/api.md), [authentication](https://docs.corsair.dev/concepts/auth.md), and [error handling](https://docs.corsair.dev/concepts/error-handling).

## Geocode

### forward

`geocode.forward`

Turn an address or place name into coordinates, a formatted address and its components, with the OpenStreetMap class and type of the match

**Risk:** `read`

```ts theme={null}
await corsair.geokeo.api.geocode.forward({ q: 'empire state building', country: 'us' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `q` | `string` | Yes | What to look up, up to 50 characters, such as `empire state building` |
| `country` | `string` | No | Restricts the search to one country, such as `us` or `de` |
| `format` | `json` | No | Response format; only `json`, which is also the default |

`q` is capped at 50 characters, and `country` is a two-letter ISO code.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `results` | `object[]` | Yes | — |
| `credits` | `string` | No | — |
| `status` | `string` | Yes | — |

> [accordion] results full type
>
> ```ts theme={null}
> {
>   class?: string,
>   type?: string,
>   address_components: {
>     name?: string,
>     island?: string,
>     neighbourhood?: string,
>     street?: string,
>     subdistrict?: string,
>     district?: string,
>     city?: string,
>     state?: string,
>     postcode?: string,
>     country?: string
>   },
>   formatted_address: string,
>   geometry: {
>     location: {
>       lat: string,
>       lng: string
>     },
>     viewport?: {
>       northeast: {
>         lat: string,
>         lng: string
>       },
>       southwest: {
>         lat: string,
>         lng: string
>       }
>     }
>   },
>   osmurl?: string,
>   importance?: number | string,
>   distance?: string,
>   lat?: number | null,
>   lng?: number | null,
>   distance_km?: number | null
> }[]
> ```

***

### reverse

`geocode.reverse`

Turn a latitude and longitude into the places nearest it, each with its address, its components and how far away it is

**Risk:** `read`

```ts theme={null}
await corsair.geokeo.api.geocode.reverse({ lat: 40.74842, lng: -73.9856 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `lat` | `number` | Yes | Latitude of the point to reverse |
| `lng` | `number` | Yes | Longitude of the point to reverse |
| `format` | `json` | No | Response format; only `json`, which is also the default |

A result carries `distance` as a string with the unit glued on, plus a parsed `distance_km`. Geokeo refuses a `lat` or `lng` of exactly `0` with `INVALID_REQUEST`.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `results` | `object[]` | Yes | — |
| `credits` | `string` | No | — |
| `status` | `string` | Yes | — |

> [accordion] results full type
>
> ```ts theme={null}
> {
>   class?: string,
>   type?: string,
>   address_components: {
>     name?: string,
>     island?: string,
>     neighbourhood?: string,
>     street?: string,
>     subdistrict?: string,
>     district?: string,
>     city?: string,
>     state?: string,
>     postcode?: string,
>     country?: string
>   },
>   formatted_address: string,
>   geometry: {
>     location: {
>       lat: string,
>       lng: string
>     },
>     viewport?: {
>       northeast: {
>         lat: string,
>         lng: string
>       },
>       southwest: {
>         lat: string,
>         lng: string
>       }
>     }
>   },
>   osmurl?: string,
>   importance?: number | string,
>   distance?: string,
>   lat?: number | null,
>   lng?: number | null,
>   distance_km?: number | null
> }[]
> ```

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.