1. Home
  2. Woosmap IP Geolocation API: location and timezone

Locate an IP address and get its timezone in one call

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

Call it from the browser with a public key or from your server with a private key.

Create a developer accountDocumentation
automatic-geolocation

THEY Trust GEOLOCATION API

Choose the endpoint that matches the job

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

/position

Estimate a location from an IP address

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

Some fields may be omitted 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

When your stores are registered in Woosmap, a single request estimates the end user's location from their IP address and returns the stores nearby. Add limit=1 to ask 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 store locator 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

The Timezone endpoint takes latitude,longitude, not an IP address. It returns the IANA timezone, its name, and the raw and DST offsets; timestamp is optional. If /position already located the user, the timezone is already in that response.

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

See what the API returns before you integrate it

The official sample below loads on its own. Inspect the available response fields, the accuracy radius and the corresponding 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 authorized 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 authorized domains or IPs. Geolocation is available on the Pro and Enterprise plans.

City-level accuracy with an explicit radius

This is city-level accuracy, not street-level or GPS accuracy.

An explicit radius

Each response includes accuracy: the radius, in kilometers around the returned location, where the IP address is likely to be.

What to expect

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

Rate limit

The documented /position limit is 50 queries per second. With a public key, it is counted per requesting IP; with a private key, 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 authorized 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 kilometers 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 ZIP code 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