1. Home
  2. Woosmap IP Geolocation API: city-level IP lookup

Look up a city-level location from an IP address

Get an end user's location from their IP address. A single call to /position returns a city-level location and the timezone.

Query it in the browser with a public key or on your server with a private key.

Create a developer accountDocumentation
geolocation uk

THEY Trust GEOLOCATION API

Pick the endpoint for the job

Three endpoints for three jobs - with a sample response for each.

/position

Look up a location from an IP address

The response includes country, region, city and postal code, coordinates and a viewport, the accuracy radius in kilometres, and the timezone with its offsets.

Some fields may be absent when the IP data is not relevant or accurate enough.

Documentation
{
  "country_code": "US",
  "country_name": "United States",
  "city": "Alexandria",
  "region_state": "Virginia",
  "postal_code": "22309",
  "latitude": 38.719,
  "longitude": -77.1067,
  "accuracy": 5,
  "timezone": "America/New_York",
  "raw_offset": -18000,
  "dst_offset": 3600
}

/stores

Find nearby stores in the same request

With your stores registered in Woosmap, one request estimates the end user's location from their IP address and returns the stores nearby; limit=1 asks for the closest one. Stores come back only when a relevant IP location is found, with accuracy of 20 km or better; otherwise the result is empty, so provide a fallback in your application. For the complete journey, start with Store Locator.

Documentation
{
  "city": "Alexandria",
  "accuracy": 5,
  "stores": {
    "type": "FeatureCollection",
    "features": [
      {
        "properties": {
          "store_id": "STORE_ID_123456",
          "name": "My Cool Store",
          "distance": 0,
          "open": { "open_now": true }
        }
      }
    ]
  }
}

/timezone

Resolve a timezone from coordinates

Use this endpoint when you have latitude,longitude rather than an IP address. It returns the IANA timezone, its name and the raw and DST offsets; timestamp is optional. When /position has already located the user, a second request is unnecessary because the timezone is included.

Documentation
{
  "timezone": "Europe/Paris",
  "timezone_name": "CEST",
  "raw_offset": 3600,
  "dst_offset": 3600
}

See the response before you build

The official sample below loads on its own. Inspect the available fields, the accuracy radius and the matching area on a map, estimated from your current IP address.

Open in CodeSandboxView the source

Make your first Geolocation request

Add this code to the front-end JavaScript of a page whose domain is authorised for your public key. Replace YOUR_API_KEY, load the page, and read the response in the browser console.

fetch("https://api.woosmap.com/geolocation/position/?key=YOUR_API_KEY")
  .then((response) => {
    if (!response.ok) {
      throw new Error(`Request failed: ${response.status}`);
    }
    return response.json();
  })
  .then((position) => console.log(position))
  .catch((error) => console.error(error));

The sample above runs on a Woosmap demonstration key; your integration uses your project's public key, which is restricted to authorised domains or IPs. Geolocation is available on the Pro and Enterprise plans.

City-level accuracy, not a street or GPS fix

An explicit radius

accuracy is the radius, in kilometres around the returned location, where the IP address is likely to be.

In practice

For 50% of users, it is 20 km or less. Woosmap Geolocation API can be used worldwide.

Rate limit

The documented /position limit is 50 queries per second. A public key is counted per requesting IP; a private key is counted per unique end-user IP passed as a parameter.

What Etam reported after redesigning its checkout with Woosmap

After redesigning a geolocated checkout with Woosmap, the e-Commerce conversion rate increased by more than 50% compared to 2019.

Sébastien Ribeile-Commerce Domain Manager, Etam Group

This result covers the checkout project as a whole, which used Store Locator, Geolocation and Address Finder. It cannot be attributed to the Geolocation API alone.

Extremely quick to integrate.

Guillaume BrunierLead Developer, Etam

Etam reports that implementing checkout maps across four brands and around fifteen websites took approximately 20 person-days. The team also used the Woosmap console to monitor usage and run quality-assurance tests.

Read the Etam customer story

Frequently asked questions about Geolocation

The API uses the end user's IP address. It does not use GPS, Wi-Fi location data or a device identifier. The Data Processing Agreement and the authorised subprocessors list cover how that data is processed.

IP geolocation works at city level, not address level. Each response includes an accuracy field: a radius in kilometres around the returned point, inside which the IP address is likely to be. Use that radius, not just the coordinates, when deciding how to use the result.

Yes. Browser-side calls use a public key, and the browser supplies the required Referer header. Server-side calls use a private key, and can pass ip_address explicitly to locate an address other than the caller's.

Add a fallback to your application. /stores returns stores only when it finds a relevant IP location with an accuracy of 20 km or less; otherwise the result is empty. You can then ask the user for a postcode or city.

No. /position already includes the timezone and its raw and daylight-saving offsets. Use the separate /timezone endpoint when you already have coordinates.

Choose the next step for your Geolocation project

Geolocation is available on Pro and Enterprise plans. Create a developer account, review pricing, or talk to our team about high-volume usage and project-specific terms. Woosmap publishes a Service Level Agreement and a Pro plan SLA.

Create a developer accountContact us
See Geolocation pricing