# Geocoding (SBX-GEOC)

Geri geocoding (bir noktada ne var: ülke, il, ilçe, posta kodu, en yakın şehir) ve IP adresinden ülke. İleri geocoding yakında.

Sürüm: v1.0

## Kimlik doğrulama

API anahtarınızı her istekte Bearer token olarak ya da `apikey` sorgu parametresiyle gönderin:

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

Anahtar almak için https://servicebox.io/signup adresinden kaydolun ve panelden bir anahtar oluşturun. Bir ajan `POST https://api.servicebox.io/v1/accounts` ve `{"email": "...", "apis": ["geocoding"]}` ile kendisi kaydolabilir: e-posta sahibi e-postadaki bağlantıyla onaylar, ajan dönen `poll_url` adresini yoklayarak kısa ömürlü bir anahtar alır.

## Temel URL

`https://api.servicebox.io`

## Uç noktalar

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

**Kredi:** ücretsiz (çağrı başına 0 kredi)

Parametre yok.

**Örnek**

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

**Kredi:** çağrı başına 1

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `ip` | query | string | evet | An IPv4 or IPv6 address. |

**Örnek**

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

**Kredi:** çağrı başına 1

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `lat` | query | number | evet | Latitude (WGS84). |
| `lon` | query | number | evet | Longitude (WGS84). |

**Örnek**

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

## Hatalar

Hatalar, makinece okunabilir bir `type` taşıyan RFC 9457 `application/problem+json` gövdeleridir.

- `401` — anahtar eksik, bilinmiyor, süresi dolmuş ya da iptal edilmiş.
- `402` — kredi yetersiz: gövde `credits_required` ve `upgrade_url` (https://servicebox.io/pricing) taşır.
- `403` — anahtarın bu API'yi çağırma izni yok.
- `429` — hız sınırı: `retry_after` saniye bekleyin (`Retry-After` başlığıyla da gönderilir); `upgrade_url` daha büyük bir plana yönlendirir.

## Bağlantılar

- OpenAPI belgesi: https://api.servicebox.io/v1/geocoding/openapi.json
- Fiyatlandırma: https://servicebox.io/pricing?api=SBX-GEOC
- API sayfası: https://servicebox.io/apis/geocoding