Getting Started

Go from zero to your first API call in under two minutes.

1

Create an account

Sign up for a free account. No credit card required. The free tier includes 5,000 requests per month.

2

Generate an API key

Go to your Dashboard and click Create API Key. Copy the key -- it is only shown once.

3

Make your first request

Pass your API key in the X-API-Key header:

curl

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.example.com/v1/countries?limit=5

Go

req, _ := http.NewRequest("GET",
    "https://api.example.com/v1/countries?limit=5", nil)
req.Header.Set("X-API-Key", "YOUR_API_KEY")
resp, err := http.DefaultClient.Do(req)

Python

import requests

r = requests.get(
    "https://api.example.com/v1/countries",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"limit": 5}
)
print(r.json())

JavaScript

const resp = await fetch(
  "https://api.example.com/v1/countries?limit=5",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await resp.json();

Response

{
  "data": [
    {
      "id": 1,
      "iso_code": "AD",
      "name": "Andorra",
      "capital": "Andorra la Vella",
      "population": 77006,
      "continent_code": "EU"
    }
  ],
  "meta": {
    "next_cursor": "eyJpZCI6NX0",
    "has_next": true,
    "has_prev": false,
    "count": 5
  }
}
4

Explore endpoints

Check the full API reference for all available endpoints, including:

  • Countries -- /v1/countries
  • Regions -- /v1/regions
  • Cities -- /v1/cities
  • Postal Codes -- /v1/postal-codes
  • Timezones -- /v1/timezones
  • IP Geolocation -- /v1/ip/{address}
  • Search -- /v1/search?q=...

Tips

  • Field selection: Add ?fields=name,population to return only the fields you need.
  • Pagination: Use the cursor from meta.next_cursor to fetch the next page.
  • Sorting: Add ?sort=-population (prefix with - for descending).
  • Rate limits: Check X-RateLimit-Remaining response headers to monitor usage.