# Maps Encoder

> Ubah alamat menjadi koordinat dan sebaliknya lewat OpenStreetMap Nominatim.

Geocoding dan reverse geocoding untuk alamat Indonesia di atas OpenStreetMap Nominatim, dengan cache 24 jam dan pembatasan laju sesuai kebijakan Nominatim. Endpoint jarak dan polyline belum diimplementasikan. Seluruh data peta bersumber dari OpenStreetMap contributors (ODbL).

- Base URL: `https://api.apipedia.id/v1/maps`
- Autentikasi: `Authorization: Bearer apk_…` (token dari console.apipedia.id)
- Kategori: Lokasi
- Halaman: https://apipedia.id/docs/maps-encoder
- OpenAPI: https://console.apipedia.id/openapi/maps-encoder.yaml

Semua respons memakai amplop `{ "is_success", "message", "data" }` kecuali disebutkan lain. Kode error umum: lihat https://apipedia.id/docs#kode-status-error.

## Endpoint (2)

- `GET /geocode`: Alamat menjadi koordinat
- `GET /reverse`: Koordinat menjadi alamat

### Alamat menjadi koordinat

`GET https://api.apipedia.id/v1/maps/geocode`

Mencari koordinat dari nama tempat atau alamat lewat OpenStreetMap Nominatim, maksimal 5 hasil. Jawaban di-cache 24 jam dan panggilan ke Nominatim dibatasi satu per detik sesuai kebijakan layanannya. Data dari OpenStreetMap contributors (ODbL).

| Parameter | Lokasi | Tipe | Wajib | Keterangan |
|---|---|---|---|---|
| `q` | query | string | ya | Nama tempat atau alamat, minimal 3 karakter. |

Contoh request:

```bash
curl -X GET "https://api.apipedia.id/v1/maps/geocode?q=Monas%20Jakarta" \
  -H "Authorization: Bearer apk_xxxxxxxxxxxxxxxx"
```

Contoh respons (200):

```json
{
  "is_success": true,
  "message": "Hasil geocoding berhasil diambil. Data © OpenStreetMap contributors (ODbL).",
  "data": {
    "q": "Monas Jakarta",
    "jumlah": 1,
    "hasil": [
      {
        "lat": -6.1753924,
        "lon": 106.8271528,
        "display_name": "Monumen Nasional, Gambir, Jakarta Pusat, DKI Jakarta, Indonesia",
        "type": "attraction",
        "address": {
          "road": "Lapangan Monas",
          "village": null,
          "suburb": "Gambir",
          "city_district": null,
          "city": "Jakarta",
          "county": "Jakarta Pusat",
          "state": "DKI Jakarta",
          "postcode": "10110",
          "country": "Indonesia"
        }
      }
    ],
    "cached": false
  }
}
```

### Koordinat menjadi alamat

`GET https://api.apipedia.id/v1/maps/reverse`

Mencari alamat terdekat dari sepasang koordinat lewat OpenStreetMap Nominatim. Jawaban di-cache 24 jam. Data dari OpenStreetMap contributors (ODbL).

| Parameter | Lokasi | Tipe | Wajib | Keterangan |
|---|---|---|---|---|
| `lat` | query | number | ya | Lintang, -90 sampai 90. |
| `lon` | query | number | ya | Bujur, -180 sampai 180. |

Contoh request:

```bash
curl -X GET "https://api.apipedia.id/v1/maps/reverse?lat=-6.1754&lon=106.8272" \
  -H "Authorization: Bearer apk_xxxxxxxxxxxxxxxx"
```

Contoh respons (200):

```json
{
  "is_success": true,
  "message": "Alamat berhasil diambil dari koordinat. Data © OpenStreetMap contributors (ODbL).",
  "data": {
    "lat": -6.1753924,
    "lon": 106.8271528,
    "display_name": "Monumen Nasional, Gambir, Jakarta Pusat, DKI Jakarta, Indonesia",
    "type": "attraction",
    "address": {
      "road": "Lapangan Monas",
      "village": null,
      "suburb": "Gambir",
      "city_district": null,
      "city": "Jakarta",
      "county": "Jakarta Pusat",
      "state": "DKI Jakarta",
      "postcode": "10110",
      "country": "Indonesia"
    },
    "cached": false
  }
}
```
