Rannz Country API

Data negara ter-normalisasi: ibu kota, mata uang, bahasa, zona waktu, perbatasan.

GET/api/v1/countriesFreecache 24 jam

Cari negara berdasarkan nama atau region

Isi name (pencarian sebagian) atau region. Hasil dinormalisasi dan dipaginasi di sisi Rannz.

Parameter	Lokasi	Tipe	Wajib	Keterangan
name	query	string	Tidak	Nama negara (sebagian juga boleh).
region	query	africa \| americas \| asia \| europe \| oceania	Tidak	Region benua.
page	query	integer	Tidak	Nomor halaman. Default: 1. Rentang: 1 - 100.
limit	query	integer	Tidak	Jumlah item per halaman. Default: 20. Rentang: 1 - 50.

Contoh request

curl "https://layananapirannz.web.id/api/v1/countries?name=indonesia&region=asia" \
  -H "Authorization: Bearer YOUR_API_KEY"

Contoh respons sukses (200)

{
  "data": {
    "items": [
      {
        "name": "Indonesia",
        "officialName": "Republic of Indonesia",
        "code2": "ID",
        "code3": "IDN",
        "capital": "Jakarta",
        "region": "Asia",
        "subregion": "South-Eastern Asia",
        "population": 273523621,
        "areaKm2": 1904569,
        "languages": [
          "Indonesian"
        ],
        "currencies": [
          {
            "code": "IDR",
            "name": "Indonesian rupiah",
            "symbol": "Rp"
          }
        ],
        "timezones": [
          "UTC+07:00",
          "UTC+08:00",
          "UTC+09:00"
        ],
        "flag": {
          "png": "https://flagcdn.com/w320/id.png",
          "svg": "https://flagcdn.com/id.svg"
        },
        "latitude": -5,
        "longitude": 120,
        "borders": [
          "TLS",
          "MYS",
          "PNG"
        ],
        "callingCode": "+62",
        "tld": [
          ".id"
        ],
        "unMember": true
      }
    ],
    "page": 1,
    "limit": 20,
    "total": 1,
    "hasNextPage": false
  },
  "meta": {
    "requestId": "…",
    "endpoint": "countries.search",
    "cached": false
  }
}

Nilai pada contoh bersifat ilustrasi; bentuk (skema) respons sama dengan yang sebenarnya.

Contoh respons error

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Input tidak valid.",
    "requestId": "…",
    "details": [
      {
        "field": "name",
        "message": "Parameter wajib diisi"
      }
    ]
  }
}

400 INVALID_INPUT Input tidak valid (parameter hilang, tipe salah, atau di luar batas).
401 INVALID_API_KEY API key tidak ada, salah format, dicabut, atau kedaluwarsa.
403 PREMIUM_REQUIRED Endpoint membutuhkan paket Premium aktif untuk layanan tersebut.
403 KEY_RESTRICTED API key dibatasi dan tidak boleh mengakses layanan ini.
404 NOT_FOUND Endpoint atau data yang diminta tidak ditemukan.
429 RATE_LIMITED Rate limit per menit terlampaui. Lihat header Retry-After.
429 QUOTA_EXCEEDED Kuota harian terlampaui. Kuota direset 00:00 UTC.
502 UPSTREAM_ERROR Sumber data (provider upstream) gagal atau mengembalikan respons tidak valid.
502 UPSTREAM_TIMEOUT Sumber data tidak merespons dalam batas waktu.

GET/api/v1/countries/:codeFreecache 24 jam

Detail negara berdasarkan kode ISO alpha-2 atau alpha-3

Contoh: /countries/ID atau /countries/IDN.

Parameter	Lokasi	Tipe	Wajib	Keterangan
code	path	string	Ya	Kode negara ISO-3166 alpha-2 atau alpha-3.

Contoh request

curl "https://layananapirannz.web.id/api/v1/countries/ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Contoh respons sukses (200)

{
  "data": {
    "name": "Indonesia",
    "officialName": "Republic of Indonesia",
    "code2": "ID",
    "code3": "IDN",
    "capital": "Jakarta",
    "region": "Asia",
    "subregion": "South-Eastern Asia",
    "population": 273523621,
    "areaKm2": 1904569,
    "languages": [
      "Indonesian"
    ],
    "currencies": [
      {
        "code": "IDR",
        "name": "Indonesian rupiah",
        "symbol": "Rp"
      }
    ],
    "timezones": [
      "UTC+07:00",
      "UTC+08:00",
      "UTC+09:00"
    ],
    "flag": {
      "png": "https://flagcdn.com/w320/id.png",
      "svg": "https://flagcdn.com/id.svg"
    },
    "latitude": -5,
    "longitude": 120,
    "borders": [
      "TLS",
      "MYS",
      "PNG"
    ],
    "callingCode": "+62",
    "tld": [
      ".id"
    ],
    "unMember": true
  },
  "meta": {
    "requestId": "…",
    "endpoint": "countries.byCode",
    "cached": false
  }
}

Nilai pada contoh bersifat ilustrasi; bentuk (skema) respons sama dengan yang sebenarnya.

Contoh respons error

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Input tidak valid.",
    "requestId": "…",
    "details": [
      {
        "field": "code",
        "message": "Parameter wajib diisi"
      }
    ]
  }
}

400 INVALID_INPUT Input tidak valid (parameter hilang, tipe salah, atau di luar batas).
401 INVALID_API_KEY API key tidak ada, salah format, dicabut, atau kedaluwarsa.
403 PREMIUM_REQUIRED Endpoint membutuhkan paket Premium aktif untuk layanan tersebut.
403 KEY_RESTRICTED API key dibatasi dan tidak boleh mengakses layanan ini.
404 NOT_FOUND Endpoint atau data yang diminta tidak ditemukan.
429 RATE_LIMITED Rate limit per menit terlampaui. Lihat header Retry-After.
429 QUOTA_EXCEEDED Kuota harian terlampaui. Kuota direset 00:00 UTC.
502 UPSTREAM_ERROR Sumber data (provider upstream) gagal atau mengembalikan respons tidak valid.
502 UPSTREAM_TIMEOUT Sumber data tidak merespons dalam batas waktu.

GET/api/v1/countries/:code/neighborsPremiumcache 24 jam

Negara-negara yang berbatasan darat

Mengembalikan daftar negara tetangga lengkap dengan datanya. Endpoint Premium.

Parameter	Lokasi	Tipe	Wajib	Keterangan
code	path	string	Ya	Kode negara ISO-3166 alpha-2 atau alpha-3.

Contoh request

curl "https://layananapirannz.web.id/api/v1/countries/ID/neighbors" \
  -H "Authorization: Bearer YOUR_API_KEY"

Contoh respons sukses (200)

{
  "data": {
    "country": "Indonesia",
    "neighbors": [
      {
        "name": "Malaysia",
        "officialName": "Republic of Indonesia",
        "code2": "MY",
        "code3": "MYS",
        "capital": "Jakarta",
        "region": "Asia",
        "subregion": "South-Eastern Asia",
        "population": 273523621,
        "areaKm2": 1904569,
        "languages": [
          "Indonesian"
        ],
        "currencies": [
          {
            "code": "IDR",
            "name": "Indonesian rupiah",
            "symbol": "Rp"
          }
        ],
        "timezones": [
          "UTC+07:00",
          "UTC+08:00",
          "UTC+09:00"
        ],
        "flag": {
          "png": "https://flagcdn.com/w320/id.png",
          "svg": "https://flagcdn.com/id.svg"
        },
        "latitude": -5,
        "longitude": 120,
        "borders": [
          "TLS",
          "MYS",
          "PNG"
        ],
        "callingCode": "+62",
        "tld": [
          ".id"
        ],
        "unMember": true
      }
    ]
  },
  "meta": {
    "requestId": "…",
    "endpoint": "countries.neighbors",
    "cached": false
  }
}

Nilai pada contoh bersifat ilustrasi; bentuk (skema) respons sama dengan yang sebenarnya.

Contoh respons error

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Input tidak valid.",
    "requestId": "…",
    "details": [
      {
        "field": "code",
        "message": "Parameter wajib diisi"
      }
    ]
  }
}

400 INVALID_INPUT Input tidak valid (parameter hilang, tipe salah, atau di luar batas).
401 INVALID_API_KEY API key tidak ada, salah format, dicabut, atau kedaluwarsa.
403 PREMIUM_REQUIRED Endpoint membutuhkan paket Premium aktif untuk layanan tersebut.
403 KEY_RESTRICTED API key dibatasi dan tidak boleh mengakses layanan ini.
404 NOT_FOUND Endpoint atau data yang diminta tidak ditemukan.
429 RATE_LIMITED Rate limit per menit terlampaui. Lihat header Retry-After.
429 QUOTA_EXCEEDED Kuota harian terlampaui. Kuota direset 00:00 UTC.
502 UPSTREAM_ERROR Sumber data (provider upstream) gagal atau mengembalikan respons tidak valid.
502 UPSTREAM_TIMEOUT Sumber data tidak merespons dalam batas waktu.

Parameter

Lokasi

Tipe

Wajib

Keterangan

name

query

string

Tidak

Nama negara (sebagian juga boleh).

region

query

africa | americas | asia | europe | oceania

Tidak

Region benua.

page

query

integer

Tidak

Nomor halaman. Default: 1. Rentang: 1 - 100.

limit

query

integer

Tidak

Jumlah item per halaman. Default: 20. Rentang: 1 - 50.

{ "data": { "items": [ { "name": "Indonesia", "officialName": "Republic of Indonesia", "code2": "ID", "code3": "IDN", "capital": "Jakarta", "region": "Asia", "subregion": "South-Eastern Asia", "population": 273523621, "areaKm2": 1904569, "languages": [ "Indonesian" ], "currencies": [ { "code": "IDR", "name": "Indonesian rupiah", "symbol": "Rp" } ], "timezones": [ "UTC+07:00", "UTC+08:00", "UTC+09:00" ], "flag": { "png": "https://flagcdn.com/w320/id.png", "svg": "https://flagcdn.com/id.svg" }, "latitude": -5, "longitude": 120, "borders": [ "TLS", "MYS", "PNG" ], "callingCode": "+62", "tld": [ ".id" ], "unMember": true } ], "page": 1, "limit": 20, "total": 1, "hasNextPage": false }, "meta": { "requestId": "…", "endpoint": "countries.search", "cached": false } }

{ "error": { "code": "INVALID_INPUT", "message": "Input tidak valid.", "requestId": "…", "details": [ { "field": "name", "message": "Parameter wajib diisi" } ] } }

Parameter

Lokasi

Tipe

Wajib

Keterangan

code

path

string

Kode negara ISO-3166 alpha-2 atau alpha-3.

{ "data": { "name": "Indonesia", "officialName": "Republic of Indonesia", "code2": "ID", "code3": "IDN", "capital": "Jakarta", "region": "Asia", "subregion": "South-Eastern Asia", "population": 273523621, "areaKm2": 1904569, "languages": [ "Indonesian" ], "currencies": [ { "code": "IDR", "name": "Indonesian rupiah", "symbol": "Rp" } ], "timezones": [ "UTC+07:00", "UTC+08:00", "UTC+09:00" ], "flag": { "png": "https://flagcdn.com/w320/id.png", "svg": "https://flagcdn.com/id.svg" }, "latitude": -5, "longitude": 120, "borders": [ "TLS", "MYS", "PNG" ], "callingCode": "+62", "tld": [ ".id" ], "unMember": true }, "meta": { "requestId": "…", "endpoint": "countries.byCode", "cached": false } }

{ "error": { "code": "INVALID_INPUT", "message": "Input tidak valid.", "requestId": "…", "details": [ { "field": "code", "message": "Parameter wajib diisi" } ] } }

Parameter

Lokasi

Tipe

Wajib

Keterangan

code

path

string

Kode negara ISO-3166 alpha-2 atau alpha-3.

{ "data": { "country": "Indonesia", "neighbors": [ { "name": "Malaysia", "officialName": "Republic of Indonesia", "code2": "MY", "code3": "MYS", "capital": "Jakarta", "region": "Asia", "subregion": "South-Eastern Asia", "population": 273523621, "areaKm2": 1904569, "languages": [ "Indonesian" ], "currencies": [ { "code": "IDR", "name": "Indonesian rupiah", "symbol": "Rp" } ], "timezones": [ "UTC+07:00", "UTC+08:00", "UTC+09:00" ], "flag": { "png": "https://flagcdn.com/w320/id.png", "svg": "https://flagcdn.com/id.svg" }, "latitude": -5, "longitude": 120, "borders": [ "TLS", "MYS", "PNG" ], "callingCode": "+62", "tld": [ ".id" ], "unMember": true } ] }, "meta": { "requestId": "…", "endpoint": "countries.neighbors", "cached": false } }

{ "error": { "code": "INVALID_INPUT", "message": "Input tidak valid.", "requestId": "…", "details": [ { "field": "code", "message": "Parameter wajib diisi" } ] } }