# Geonames — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search for places worldwide and get their exact coordinates, timezone information, and elevation data, or reverse lookup locations by coordinates to discover nearby areas. Access postal codes, country details, and geographic names across the globe to build location-aware applications and services.

**Category:** Maps & Geospatial | **Website:** [geonames.org/](https://geonames.org/) | **Docs:** [parse.bot/marketplace/57737138-f447-4aa6-969e-751b1d70f550/geonames-org-api](https://parse.bot/marketplace/57737138-f447-4aa6-969e-751b1d70f550/geonames-org-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-geonames-org-api-57737138/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_place_by_id

Fetch full details for a specific geographic place using its GeoNames ID. Returns comprehensive data including timezone, bounding box, population, alternate names, administrative hierarchy, and continent code. One round-trip per place; use search_places to discover IDs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `geoname_id` | integer | Yes | GeoNames ID of the place (from search_places results) |
| `style` | string | No | Response verbosity: SHORT, MEDIUM, LONG, FULL |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-geonames-org-api-57737138/get_place_by_id \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"geoname_id":"<integer>","style":"<string>"}'
```

### postal_code_country_info

Get metadata about postal code coverage per country. Returns the number of postal codes, min and max postal code values for each country with postal code data. No parameters required; returns all countries.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-geonames-org-api-57737138/postal_code_country_info \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### postal_code_search

Search postal/ZIP codes and associated places. At least one search parameter (postalcode, placename, postalcode_startsWith, or placename_startsWith) should be provided along with a country filter for best results. Returns matching postal code entries with geographic coordinates and admin division info.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country` | string | No | ISO country code to filter by |
| `limit` | integer | No | Maximum number of results |
| `placename` | string | No | Place name to search for |
| `placename_startsWith` | string | No | Place name prefix to search |
| `postalcode` | string | No | Postal code to search for |
| `postalcode_startsWith` | string | No | Postal code prefix to search |
| `style` | string | No | Response verbosity: SHORT, MEDIUM, LONG, FULL |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-geonames-org-api-57737138/postal_code_search \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"<string>","limit":"<integer>","placename":"<string>","placename_startsWith":"<string>","postalcode":"<string>","postalcode_startsWith":"<string>","style":"<string>"}'
```

### reverse_geocode_find_nearby

Find the nearest toponyms for a given latitude/longitude. Returns nearby geographic features sorted by distance ascending. Each result includes a distance field (in km) from the query point.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `lat` | number | Yes | Latitude |
| `limit` | integer | No | Maximum number of results |
| `lng` | number | Yes | Longitude |
| `radius` | number | No | Search radius in km |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-geonames-org-api-57737138/reverse_geocode_find_nearby \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lat":"<number>","limit":"<integer>","lng":"<number>","radius":"<number>"}'
```

### search_places

Search for geographic places/toponyms by name, country, feature class, bounding box, or coordinates. Returns paginated results ordered by relevance by default. At least one search parameter (query, name, or name_equals) should be provided for meaningful results; combining with country or featureClass narrows the result set. Offset-based pagination: pass offset to advance through pages of results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `continentCode` | string | No | Continent code: AF, AS, EU, NA, OC, SA, AN |
| `country` | string | No | ISO-3166 country code to filter by |
| `east` | number | No | Bounding box east longitude |
| `featureClass` | string | No | GeoNames feature class: A, H, L, P, R, S, T, U, V |
| `featureCode` | string | No | GeoNames feature code (e.g. PPLC, ADM1, PPL) |
| `fuzzy` | number | No | Fuzzy matching factor (0-1) |
| `lang` | string | No | Language for place names (ISO-639) |
| `limit` | integer | No | Maximum number of results to return |
| `name` | string | No | Place name to search for |
| `name_equals` | string | No | Exact place name match |
| `north` | number | No | Bounding box north latitude |
| `offset` | integer | No | Offset for pagination (number of items to skip) |
| `orderby` | string | No | Order results by: relevance, population, elevation |
| `query` | string | No | General search query for place names |
| `south` | number | No | Bounding box south latitude |
| `style` | string | No | Response verbosity: SHORT, MEDIUM, LONG, FULL |
| `west` | number | No | Bounding box west longitude |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-geonames-org-api-57737138/search_places \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"continentCode":"<string>","country":"<string>","east":"<number>","featureClass":"<string>","featureCode":"<string>","fuzzy":"<number>","lang":"<string>","limit":"<integer>","name":"<string>","name_equals":"<string>","north":"<number>","offset":"<integer>","orderby":"<string>","query":"<string>","south":"<number>","style":"<string>","west":"<number>"}'
```

### timezone

Get timezone information for any latitude/longitude. Returns the timezone ID, GMT/DST offsets, raw offset, current local time, and sunrise/sunset times for the given coordinates.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `lat` | number | Yes | Latitude |
| `lng` | number | Yes | Longitude |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-geonames-org-api-57737138/timezone \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lat":"<number>","lng":"<number>"}'
```