API Overview

The hosted API exposes the package datasets and rendering helpers over straightforward JSON endpoints.

Base URL

https://api.arevdata.com

Common response format

Successful responses use a data envelope and may include meta:

{
  "data": [],
  "meta": {
    "count": 0
  }
}

Errors use an error object:

{
  "error": {
    "code": "invalid_query",
    "message": "limit must be a positive integer"
  }
}

API access

Hosted access is intentionally capped. For API keys, authentication headers, signup flow, and upgrade requests, see API Access.

Endpoints

Method Path Overview Details
GET /health Healthcheck for uptime and worker diagnostics. Health
GET /meta Dataset counts, supported languages, and route inventory. Meta
POST /access/signup Start the free API key signup flow by email. Signup
GET /access/verify?token=... Verify the emailed token and reveal a free API key. Verify
POST /access/request-upgrade Submit a manual review request for a higher tier. Request Upgrade
GET /address-formats Full address-format dataset keyed by country. Address Formats
GET /address-formats/:alpha2 Single address-format record by alpha-2 country code. Address Format by Country
GET /countries Country collection with localization and filters. Countries
GET /countries/:alpha2 Single country record by alpha-2 code. Country by Code
GET /cities City collection with search, filtering, and limits. Cities
GET /cities/capital/:alpha2 Capital city record for a country. Capital City
GET /phone-codes Phone-code mappings with lookup and search. Phone Codes
GET /timezones IANA timezone mappings with lookup and search. Timezones
GET /maps/world JSON response containing a rendered SVG world map. World Map
GET /astronomy Moon-phase and hemisphere-aware season snapshot for a date. Astronomy

Notes

  • Every endpoint above has its own page with request inputs, examples, and response shapes.
  • All routes support OPTIONS.
  • POST is only supported for /access/signup and /access/request-upgrade.
  • JSON endpoints include CORS headers for browser-based demos and integrations.
  • Collection endpoints that return arrays may include meta.count.
  • Requests that exceed burst or daily limits return 429 with Retry-After.

Explore the API reference