Skip to content

Help guide_

From zero to your first localised checkout in five minutes.

Keys, restrictions, quotas, FX freshness, error handling and migration — the honest, practical version.

Create an account API reference
  1. 1 Create a free account
  2. 2 Generate a key
  3. 3 Restrict it
  4. 4 First call in minutes
Quickstart

Get running in 5 minutes

  1. 1

    Create an account

    Sign up — no card needed.

  2. 2

    Create a key

    Generate a key in the dashboard, then copy it immediately: we store only its hash and cannot show it again.

  3. 3

    Call from your server

    Never from the browser — a key in client-side JavaScript is a key you have given away.

quickstart.sh 
curl "https://api.localesense.com/v1/lookup?ip=203.135.62.10" \
    -H "Authorization: Bearer ls_test_..."

Start with a ls_test_ key while you build; it behaves identically and keeps your live usage clean.

Keys_

Managing keys

01

Keys carry their own tier, rate limit and quota, so you can hand a low-limit key to a staging environment without touching production. Revoking a key takes effect immediately — there is no cache window during which a revoked key still works.

02

If a key leaks: revoke it in the dashboard, create a new one, deploy. In that order. A revoked key cannot be un-revoked, which is the point.

Restrictions_

IP and domain restrictions

Every tier can bind a key to a set of source IPs (CIDR ranges are supported) or to the domains allowed to originate a request. A key that only works from your servers is a key that a leaked .env file cannot monetise.

Restrictions fail closed: if a request does not match an allow rule, it is refused with origin_not_allowed. Add your rules before you deploy, not after.

Tiers & quotas_

Tiers and quotas

Quotas are monthly and reset on the first. When one is exhausted the API returns 429 — it does not start billing you, and it does not quietly return thinner data. Usage is visible in the dashboard in near-real time.

Tier upgrades apply to your next request, not your next billing cycle. See the tier table.

FX sources_

FX sources and freshness

Rates come from central banks — the ECB, the US Federal Reserve, the State Bank of Pakistan — and are refreshed hourly. Central banks publish once a day on business days, so a rate's as_of date is the honest answer to "how fresh is this", not the time we fetched it.

When a source goes quiet past its window, we mark the rate stale: true rather than hiding it or serving a guess. If no source publishes a currency at all, the fx block is absent — an absent block is a fact; a fabricated rate is a liability. Live source health is on the status page.

Errors_

Error handling

The rule that matters: never fail a checkout because an enrichment call failed. Wrap the call, set a short timeout, and fall back to your own defaults. We are a better answer than your default — we are not a better answer than a completed sale.

A 422 geo_lookup_failed is normal traffic, not a bug: private ranges, reserved space and satellite blocks genuinely cannot be placed. Treat it as "unknown", not as an outage. Full codes are in the API reference.

Migrating_

Migrating from another provider

The shapes are similar enough that most migrations are a field rename and a mental adjustment: geo APIs give you a location, and you were building the commerce logic yourself. Here you stop building it.

ipapi

Coming from ipapi

Same request shape, but you can delete your hand-maintained currency-decimals table.

Read the guide ipinfo

Coming from ipinfo

ASN and privacy detection map across directly; the tax and payment blocks are new.

Read the guide MaxMind

Coming from MaxMind

We use GeoLite2 for geography too, so your accuracy does not change. Everything above geography is what's new.

Read the guide
FAQs

Getting-started questions

How do I get a LocaleSense API key?

Create a free account, open the dashboard and generate a key. It is displayed exactly once — we store only a SHA-256 hash — so copy it into your secret manager immediately. The free tier is 10,000 requests a month, no card required.

How do I stop my API key being abused if it leaks?

Restrict it. A key can be locked to specific domains, IP addresses or CIDR ranges from the dashboard, and restrictions fail closed — a request from anywhere else is rejected even with a valid key. You can also revoke a key instantly; revocation takes effect immediately.

What counts against my monthly quota?

Only successful responses — anything with a status below 400. Validation errors, auth failures and rate-limit rejections are never billed, and a batch call declares its real weight (one call with 50 IPs counts as 50).

How do I migrate from ipapi, ipinfo or MaxMind?

The response is a superset of a geo lookup, so your existing country logic keeps working — you read the same country field, then start using the commerce blocks (currency, tax, payments, FX) as you need them. The comparison pages map each provider's fields to ours.