# Geocoding (SBX-GEOC)

Reverse geocoding (what is at a point: country, province, district, postal code, nearest city) and IP-address-to-country. Forward geocoding coming soon.

Version: v1.0

## Authentication

Send your API key on every request, either as a Bearer token or as the `apikey` query parameter:

```
Authorization: Bearer <YOUR_API_KEY>
https://api.servicebox.io/v1/geocoding/...?apikey=<YOUR_API_KEY>
```

Get a key: sign up at https://servicebox.io/en/signup and create one on the dashboard. An agent can sign up itself with `POST https://api.servicebox.io/v1/accounts` and `{"email": "...", "apis": ["geocoding"]}`: the owner of the mailbox approves by email and the agent collects a short-lived key by polling the returned `poll_url`.

## Base URL

`https://api.servicebox.io`

## Endpoints

### GET /v1/geocoding/coverage

**Get coverage**

What the lookups cover: the data snapshot, the sources and their licences, and the countries whose postal codes the place lookup can answer. Free.

**Credits:** free (0 credits per call)

No parameters.

**Example**

```bash
curl "https://api.servicebox.io/v1/geocoding/coverage" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/geocoding/ip-addresses/lookup

**Look up an IP address**

The country an IPv4 or IPv6 address is registered in. Country level only.

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ip` | query | string | yes | An IPv4 or IPv6 address. |

**Example**

```bash
curl "https://api.servicebox.io/v1/geocoding/ip-addresses/lookup?ip=<ip>" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/geocoding/places/lookup

**Look up a point (reverse geocoding)**

What is at a point: its country and first-level subdivision (from the nearest city of 1,000+ inhabitants within 100 km), the nearest city, and in Turkey the district and postal code of the nearest located neighbourhood or village within 5 km. Nearest-place, not boundary-based: near a border the nearest city can be across it, so each match carries its distance.

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `lat` | query | number | yes | Latitude (WGS84). |
| `lon` | query | number | yes | Longitude (WGS84). |

**Example**

```bash
curl "https://api.servicebox.io/v1/geocoding/places/lookup?lat=0&lon=0" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

## Errors

Errors are RFC 9457 `application/problem+json` bodies with a machine-readable `type`.

- `401` — the key is missing, unknown, expired or revoked.
- `402` — not enough credits: the body carries `credits_required` and `upgrade_url` (https://servicebox.io/en/pricing).
- `403` — the key is not allowed to call this API.
- `429` — rate limited: wait `retry_after` seconds (also sent as the `Retry-After` header); `upgrade_url` points to a larger plan.

## Links

- OpenAPI document: https://api.servicebox.io/v1/geocoding/openapi.json
- Pricing: https://servicebox.io/en/pricing?api=SBX-GEOC
- API page: https://servicebox.io/en/apis/geocoding