Live12 DB API

A distributed reference data API. Read timezones, country metadata and the current time from 30 regional edge endpoints — all behind a small, stable set of GET endpoints that return versioned JSON.

Every response is plain JSON over HTTPS. No SDK is required. Public endpoints (health, status, regions) need no authentication; dataset endpoints require an API key passed as a Bearer token.

Quickstart

1. Get an API key. Pick a plan on the pricing page and we will provision a key. Keys must be at least 8 characters long.

2. Check that the edge is up — no key needed:

# Liveness check against the nearest edge node
curl -s https://nl.live12db.com/v1/health

3. Make an authenticated request with your key as a Bearer token:

# Look up the Netherlands by ISO code
curl -s https://nl.live12db.com/v1/countries?code=NL \
  -H "Authorization: Bearer $LIVE12_KEY"

That is it. The same calls work against any of the 30 regional endpoints.

Base URL & regions

All requests go to a regional base URL:

https://{region}.live12db.com/v1

{region} is a two-letter region code, for example nl (Amsterdam), de (Frankfurt) or lv (Riga). Fetch the full list any time from GET /v1/regions. Pin a region with its subdomain, or let geo-routing pick the nearest node. Your current edge is nl.live12db.com.

Response headers

Every response includes:

X-Request-Id — a unique ID for the request, useful for support.
X-Live12-Region — the region code that served the response.

Authenticated (protected) endpoints additionally return rate-limit headers:

X-RateLimit-Limit — requests allowed in the window (1000).
X-RateLimit-Remaining — requests remaining in the current window.
X-RateLimit-Reset — Unix timestamp when the window resets.

Authentication

Dataset endpoints require an API key. Pass it as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Alternatively, send it in the X-API-Key header:

X-API-Key: YOUR_API_KEY

Keys must be at least 8 characters. Requests to protected endpoints without a valid key return 401 unauthorized. Public endpoints ignore the header.

Examples in three languages:

# curl
curl -s https://nl.live12db.com/v1/timezones \
  -H "Authorization: Bearer $LIVE12_KEY"

// JavaScript (fetch)
const res = await fetch("https://nl.live12db.com/v1/countries?code=NL", {
  headers: { Authorization: `Bearer ${process.env.LIVE12_KEY}` }
});
const data = await res.json();

# Python (requests)
import os, requests

res = requests.get(
    "https://nl.live12db.com/v1/time",
    params={"tz": "Europe/Riga"},
    headers={"Authorization": f"Bearer {os.environ['LIVE12_KEY']}"},
)
data = res.json()

API reference

All endpoints are GET only. Any other method returns 405 method_not_allowed. Paths below are relative to https://{region}.live12db.com/v1.

Method	Path	Auth	Description
GET	`/health`	None	Liveness probe.
GET	`/status`	None	Edge node status.
GET	`/regions`	None	List regional endpoints.
GET	`/timezones`	Bearer	Timezones with current offsets.
GET	`/countries`	Bearer	Country reference data.
GET	`/time`	Bearer	Current time for a timezone.

GET /health

Liveness probe. No authentication. Returns the serving region and a timestamp.

curl -s https://nl.live12db.com/v1/health

{
  "status": "ok",
  "region": "nl",
  "timestamp": "2026-05-28T12:00:00+00:00"
}

GET /status

Edge node status. No authentication. Reports the build, region, number of nodes online and latency.

curl -s https://nl.live12db.com/v1/status

{
  "status": "operational",
  "build": "2026.5.3",
  "region": {
    "code": "nl",
    "city": "Amsterdam",
    "country": "Netherlands"
  },
  "nodes_online": 30,
  "latency_ms": 12,
  "timestamp": "2026-05-28T12:00:00+00:00"
}

GET /regions

Lists all regional endpoints. No authentication. Each entry has a code, city, country, continent and endpoint base URL.

curl -s https://nl.live12db.com/v1/regions

{
  "object": "list",
  "count": 30,
  "data": [
    {
      "code": "nl",
      "city": "Amsterdam",
      "country": "Netherlands",
      "continent": "Europe",
      "endpoint": "https://nl.live12db.com/v1"
    }
  ]
}

GET /timezones

Lists timezones with their current UTC offset. Requires authentication.

curl -s https://nl.live12db.com/v1/timezones \
  -H "Authorization: Bearer $LIVE12_KEY"

{
  "object": "list",
  "count": 28,
  "data": [
    {
      "timezone": "Europe/Amsterdam",
      "abbreviation": "CEST",
      "utc_offset": "+02:00"
    }
  ]
}

GET /countries

Country reference data. Requires authentication.

Query parameters

Parameter	Type	Description
`code`	string	Filter by ISO 3166-1 alpha-2 or alpha-3 code (e.g. `NL` or `NLD`).
`currency`	string	Filter by ISO 4217 currency code (e.g. `EUR`).

curl -s "https://nl.live12db.com/v1/countries?code=NL" \
  -H "Authorization: Bearer $LIVE12_KEY"

{
  "object": "list",
  "count": 1,
  "data": [
    {
      "iso2": "NL",
      "iso3": "NLD",
      "name": "Netherlands",
      "capital": "Amsterdam",
      "region": "Europe",
      "currency": "EUR",
      "calling_code": "+31"
    }
  ]
}

Omitting both parameters returns the full dataset. Filters can be combined.

GET /time

Current time for a timezone. Requires authentication.

Query parameters

Parameter	Type	Description
`tz`	string	IANA timezone name (e.g. `Europe/Riga`). Defaults to the serving region’s timezone. An unknown value returns `422 invalid_argument`.

curl -s "https://nl.live12db.com/v1/time?tz=Europe/Riga" \
  -H "Authorization: Bearer $LIVE12_KEY"

{
  "timezone": "Europe/Riga",
  "datetime": "2026-05-28T15:00:00+03:00",
  "unixtime": 1779019200,
  "utc_offset": "+03:00",
  "abbreviation": "EEST",
  "day_of_week": 4,
  "week_number": 22
}

day_of_week follows ISO-8601 (1 = Monday … 7 = Sunday); week_number is the ISO week.

Errors

Errors use a consistent envelope and standard HTTP status codes:

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key. Pass it via the Authorization: Bearer header.",
    "status": 401
  }
}

HTTP	Code	When it happens
401	`unauthorized`	Missing or invalid API key on a protected endpoint.
404	`not_found`	Unknown endpoint path.
405	`method_not_allowed`	A method other than `GET` was used.
422	`invalid_argument`	An invalid parameter, such as an unknown `tz`.

The complete machine-readable contract is published as an OpenAPI 3 spec.