Geolocation from an IP address

GET

https://api.woosmap.com/geolocation/position

The /position returns JSON location of your users thanks to IP address of their devices.

Authorization

key

apiKey query

A Public key generated specifically to authenticate API requests on the front side. See how to register a Public API Key.

Referer

apiKey header

The Referer HTTP request header is mandatory when using PublicApiKeyAuth. In browser environment, the Referer is set by the browser itself and cannot be overridden.

private_key

apiKey query

A Private key generated specifically to authenticate API requests on server side. Required for Data management API. See how to register a Private API Key.

X-Api-Key

apiKey header

A Private key to authenticate API requests through the Header instead of Query parameter. Use either PrivateApiKeyHeaderAuth or PrivateApiKeyAuth. See how to register a Private API Key.

Query Parameters

ip_address

string

The ip_address you want to geolocate. For server call with private_key only. Without this parameter, the API will geolocate the IP Address attached to the raw TCP request.

Example: 75.134.29.90

Response

200 application/json

Geolocation successfully retrieved

viewport

object

A rectangle in geographical coordinates from points at the southwest and northeast corners.

Example:

JSON

        
{
  "northeast": {
    "lat": 49.315678,
    "lng": 4.15292
  },
  "southwest": {
    "lat": 49.31073,
    "lng": 4.145162
  }
}

    

Show 2 propertiesHide 2 properties

viewport. northeast

object

An object describing a specific location with Latitude and Longitude in decimal degrees.

Example:

JSON

        
{
  "lat": 43.3,
  "lng": 3.46
}

    

Show 2 propertiesHide 2 properties

viewport.northeast. lat

number required

Latitude in decimal degrees

Example: 42.3

viewport.northeast. lng

number required

Longitude in decimal degrees

Example: 3.46

viewport. southwest

object

An object describing a specific location with Latitude and Longitude in decimal degrees.

Example:

JSON

        
{
  "lat": 43.3,
  "lng": 3.46
}

    

Show 2 propertiesHide 2 properties

viewport.southwest. lat

number required

Latitude in decimal degrees

Example: 42.3

viewport.southwest. lng

number required

Longitude in decimal degrees

Example: 3.46

accuracy

number

The accuracy of the estimated location, in kilometers. This represents the radius of a circle around the given location where the IP address is likely to be. If your Geolocation response shows a low value in the accuracy field (<=50), the IP has strong chance to be correctly located.

Example: 5

latitude

number

Approximate latitude of the geographical area associated with the IP address

Example: 38.719

longitude

number

Approximate longitude of the geographical area associated with the IP address

Example: -77.1067

country_code

string | null

ISO 3166-1 Alpha-2 compatible country code

Example: US

country_name

string

Country name

Example: United States

continent

string

Continent name

Example: North America

region_state

string

Region name when available

Example: Virginia

city

string

City name when available

Example: Alexandria

postal_code

string

A postal code close to the user's location, when available

Example: 22309

timezone

string

Timezone for the Opening Hours of an Asset. It is used to compute the open_now property of an asset. see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

Example: Europe/London

raw_offset

integer

The offset from utc in seconds

Example: -18000

dst_offset

integer

The daylight saving time offset in seconds

Example: 3600

Errors

401

Unauthorized. Incorrect authentication credentials.

application/json

detail

string

Details for the credentials error

Example: Incorrect authentication credentials. Please check or use a valid API Key

403

Forbidden. This Woosmap API is not enabled for this project.

application/json

detail

string

Details for the forbidden error message

Example: This Woosmap API is not enabled for this project.

429

Too Many Requests. The rate limit for this endpoint has been exceeded.

application/json

detail

string

Details for the Over Query Limit error message

Example: The rate limit for this endpoint has been exceeded

cURL

JavaScript

Python

        curl -L 'https://api.woosmap.com/geolocation/position?private_key=YOUR_PRIVATE_API_KEY&ip_address=173.79.254.254'

    

        const requestOptions = {
  method: "GET",
  redirect: "follow"
};

fetch("https://api.woosmap.com/geolocation/position?private_key=YOUR_PRIVATE_API_KEY&ip_address=173.79.254.254", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

    

        import requests

url = "https://api.woosmap.com/geolocation/position?private_key=YOUR_PRIVATE_API_KEY&ip_address=173.79.254.254"

payload = {}
headers = {}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)


    

200

401

403

429

        
{
  "country_code": "US",
  "country_name": "United States",
  "continent": "North America",
  "latitude": 38.719,
  "longitude": -77.1067,
  "viewport": {
    "northeast": {
      "lat": 38.763915764205976,
      "lng": -77.0491321464058
    },
    "southwest": {
      "lat": 38.674084235794034,
      "lng": -77.16426785359421
    }
  },
  "accuracy": 5,
  "city": "Alexandria",
  "region_state": "Virginia",
  "postal_code": "22309",
  "timezone": "America/New_York",
  "raw_offset": -18000,
  "dst_offset": 3600
}

    

        
{
  "detail": "Incorrect authentication credentials. Please check or use a valid API Key"
}

    

        
{
  "detail": "This Woosmap API is not enabled for this project."
}

    

        
{
  "detail": "The rate limit for this endpoint has been exceeded"
}

    

Was this helpful?

Failed to send feedback. Please try again.

Thanks for your feedback!