VisitorGeo API

One authenticated GET returns the caller’s approximate location and network. Everything is an IP-based estimate.

Endpoint

GET https://api.visitorgeo.com/v1/YOUR_KEY

The key is the 16-character key issued at signup. The response describes the caller of the request — i.e. the browser or server that made the GET. Call it from your visitor’s browser to geolocate that visitor.

Response fields

All fields are optional: any value Cloudflare cannot resolve for a given IP is omitted from the JSON rather than returned empty. estimated is always present and always true.

Field	Type	Notes
`estimated`	boolean	Always `true`. All data is an IP-derived estimate.
`ip`	string	The caller’s IP address.
`country`	string	ISO 3166-1 alpha-2 country code, e.g. `US`.
`city`	string	Best-guess city name.
`region`	string	First-level subdivision (state/province) name.
`region_code`	string	Subdivision code, e.g. `CA`.
`postal_code`	string	Postal/ZIP code for the IP’s area.
`metro_code`	string	DMA/metro code (US only, when available).
`latitude`	number	Area centroid latitude. Not a GPS fix — accuracy is city/region level.
`longitude`	number	Area centroid longitude. Same caveat as latitude.
`timezone`	string	IANA timezone, e.g. `America/Los_Angeles`.
`continent`	string	Two-letter continent code.
`asn`	number	Autonomous System Number of the IP’s network.
`as_organization`	string	Name of the network operator.
`colo`	string	Cloudflare data center (IATA code) that served the request.

CORS

Every response sends Access-Control-Allow-Origin: *, so you can call the API directly from browser JavaScript on any origin. Preflight OPTIONS requests are answered with 204. All responses send Cache-Control: no-store.

Latency tip

The lookup itself returns in roughly 30 ms from the Cloudflare datacenter nearest your visitor. The first request from a page also pays the TLS handshake; overlap that with page load by adding a preconnect hint to your <head>:

<link rel="preconnect" href="https://api.visitorgeo.com" crossorigin>

Key security

From your dashboard you can restrict a key to an allowlist of domains and set an optional monthly request cap.

Allowed domains — one host per line (e.g. example.com). When set, the worker checks the request’s Origin header (falling back to Referer). Exact host and subdomains match; requests with neither header are rejected. Leave empty to allow any origin. Allowlist changes reach the edge within about five minutes.
Monthly request cap — when month-to-date estimated lookups exceed the cap, the key returns 429 until the next UTC month (or until you raise/clear the cap). Cap state is reconciled about hourly from metered usage.

Error codes

Status	Body	Meaning
`403`	`{"error":"unknown or disabled account key"}`	The key is not recognized or has been disabled.
`403`	`{"error":"origin not allowed"}`	The request’s Origin/Referer host is not on the key’s allowed-domains list.
`429`	`{"error":"monthly request cap reached"}`	The key is capped: either month-to-date estimated lookups exceeded your configured monthly cap, or you served past the 1,000/month free tier with an empty prepaid balance. Load your balance (or raise/clear the cap) to restore service.
`404`	`{"error":"not found"}`	Bad path, or a malformed key (must be 12–24 lowercase alphanumeric characters).

Fair use

Commercial use is allowed on every tier, including the free tier — use VisitorGeo in commercial sites, products, and client work.

Keys are metered per lookup. Please don’t share a key across unrelated properties or attempt to defeat metering — usage that looks abusive may have its key disabled. Billing is $1 per million lookups with the first 1,000 lookups each month free. Usage beyond the free tier draws down a prepaid balance you load from your dashboard; optional auto-reload tops it up from your saved card. See pricing.

Get a key