API reference (v1)

The v1 API returns likely area codes from approximate network geolocation, plus IP and ASN intelligence. Results are estimates, never an exact answer. The base URL is https://whatsmyareacode.com and every path below is prefixed with /api/v1.

Response envelope

Successful responses share a stable envelope:

{ "ok": true, "data": { ... }, "meta": { "request_id", "cache", "dataset_release", "evidence_as_of", "evidence_dates", "generated_at" } }

Errors use a parallel shape and never leak upstream details:

{ "ok": false, "error": { "code": "RATE_LIMITED", "message": "…", "retryable": true, "retry_after_seconds": 30 } }

meta.evidence_as_of is the oldest source date the answer actually relied on — not a build date. meta.generated_at is only the response time and never stands in for data freshness.

IP responses may include map: { center: [x, y], precision: "city" }. The tuple uses GeoJSON order (longitude-like x, latitude-like y), is rounded to city precision, and is not browser, device, or street-level location. Raw upstream coordinate fields are not exposed.

Endpoints

Method & path	Purpose	Notes
`GET /area-codes/current`	Likely area codes for the caller's IP.	No parameters. Non-NANP returns `coverage: "unsupported"` at HTTP 200, not an error.
`GET /area-codes/search`	Search by area code, place or region.	`kind` required (`npa`, `place`, `region`). `place` needs `country`, plus `region` for US/CA. Duplicate place names return `status: "ambiguous"` with choices.
`GET /area-codes/{npa}`	Official record for one area code.	`npa` matches `^[2-9][0-9]{2}$`. Supports ETag / 304.
`GET /ips/current`	IP intelligence for the caller's IP.	No parameters.
`GET /ips/{ip}`	IP intelligence for a given IPv4/IPv6 literal.	Hostnames, URLs, CIDR, ports and zone ids are rejected as `INVALID_IP`.
`GET /asns/{asn}`	ASN summary.	Accepts `AS15169` or `15169`. Radar summary may be null.
`GET /health`	Liveness and active dataset id.	Minimal body `{ "ok": true, "dataset_release": "…" }`. Not a free IP probe.

Authentication

This v1 surface is anonymous by design. Every endpoint is available without an account, session cookie or API key; the API does not accept credentials and does not expose a login flow.

Rate limits

Tier	Limit	How
Anonymous	60 requests / minute	Per client (salted HMAC of IP).

Rate-limit headers (X-RateLimit-Limit, -Remaining, -Reset) appear on non-cacheable routes only, so cached copies never carry stale quota state.

Errors and retries

429 and 503 responses are retryable and carry both a Retry-After header and error.retry_after_seconds. Wait at least that long before retrying.

Code	HTTP	Meaning
`INVALID_QUERY`	400	Malformed or unsupported parameters.
`INVALID_IP`	400	IP address is not a valid literal.
`INVALID_ASN`	400	ASN is not valid.
`AREA_CODE_NOT_FOUND`	404	No record for that area code.
`METHOD_NOT_ALLOWED`	405	Method not allowed; see the `Allow` header.
`RATE_LIMITED`	429	Slow down and retry after the given delay.
`UPSTREAM_RATE_LIMITED`	429	Upstream provider is rate limiting; retry later.
`UPSTREAM_UNAVAILABLE`	502 / 503	Upstream IP lookup temporarily unavailable.
`DATASET_UNAVAILABLE`	503	Area-code data temporarily unavailable.
`INTERNAL_ERROR`	500	Unexpected server error; the response carries a request id.

Method handling

HEAD mirrors GET without a body. Unlisted methods return 405 with an Allow header. There is no cross-origin surface, so OPTIONS is not a preflight endpoint.