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

# Geo

> Canonical travel geography: countries, regions, cities, ports, and waterways, plus language and timezone reference data.

The `geo` namespace serves canonical travel geography. It is the reference data behind location pickers, itinerary mapping, and place resolution: countries, regions, cities, ports, and waterways, plus language and timezone lookups.

Geo requires the `data:geo:read` scope.

```ts theme={null}
import { createVoyantDataClient } from "@voyant-travel/data-sdk";

const client = createVoyantDataClient({ apiKey: process.env.VOYANT_API_KEY! });
```

## Countries and regions

```ts theme={null}
const countries = await client.geo.countries.list();
const france = await client.geo.countries.get("FR");

const regions = await client.geo.regions.list({ country: "FR" });
```

## Cities

```ts theme={null}
const matches = await client.geo.cities.search({ q: "athens", country: "GR" });

const nearby = await client.geo.cities.nearby({
  latitude: 37.98,
  longitude: 23.73,
  radiusKm: 50,
});
```

## Reference lookups

Geo also exposes the language and timezone reference catalogs:

```ts theme={null}
const languages = await client.geo.languages.list();
const timezones = await client.geo.timezones.list();
```

## Types

Key types include `CanonicalPlace`, `CanonicalPlaceType`, `PlaceWithRelations`, `PlaceResolveRequest`, `PlaceResolveResult`, `LanguageEntry`, and `TimezoneEntry`. List methods return `ListResponse<T>` and single lookups return `SingleResponse<T>`.

<Note>
  If geography reads come back empty, check that your token actually carries `data:geo:read`. An entitlement gap looks like empty data rather than an error.
</Note>