Source: https://developers.woosmap.com/api-reference/geolocation-api/get-geolocation-position/

> For clean Markdown of any page, append `.md` to the page URL.

> For a complete documentation index, see https://developers.woosmap.com/llms.txt

# Geolocation from an IP address



# 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`](#authorization-woosmap-platform-api-reference-publicapikeyauth)
apiKeyquery

A Public key generated specifically to authenticate API requests on the front side. See how to [register a Public API Key](https://developers.woosmap.com/api-reference/authentication/#registering-a-woosmap-public-api-key).

[`Referer`](#authorization-woosmap-platform-api-reference-refererheader)
apiKeyheader

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`](#authorization-woosmap-platform-api-reference-privateapikeyauth)
apiKeyquery

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](https://developers.woosmap.com/api-reference/authentication/#registering-a-woosmap-private-api-key).

[`X-Api-Key`](#authorization-woosmap-platform-api-reference-privateapikeyheaderauth)
apiKeyheader

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](https://developers.woosmap.com/api-reference/authentication/#registering-a-woosmap-private-api-key).

### Query Parameters

[`ip_address`](#query-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

200application/json

Geolocation successfully retrieved

[`viewport`](#resp-200-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`](#resp-200-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`](#resp-200-viewport-northeast-lat)
numberrequired

Latitude in decimal degrees

Example:`42.3`

viewport.northeast.[`lng`](#resp-200-viewport-northeast-lng)
numberrequired

Longitude in decimal degrees

Example:`3.46`

viewport.[`southwest`](#resp-200-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`](#resp-200-viewport-southwest-lat)
numberrequired

Latitude in decimal degrees

Example:`42.3`

viewport.southwest.[`lng`](#resp-200-viewport-southwest-lng)
numberrequired

Longitude in decimal degrees

Example:`3.46`

[`accuracy`](#resp-200-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`](#resp-200-latitude)
number

Approximate latitude of the geographical area associated with the IP address

Example:`38.719`

[`longitude`](#resp-200-longitude)
number

Approximate longitude of the geographical area associated with the IP address

Example:`-77.1067`

[`country_code`](#resp-200-country-code)
string | null

ISO 3166-1 Alpha-2 compatible country code

Example:`US`

[`country_name`](#resp-200-country-name)
string

Country name

Example:`United States`

[`continent`](#resp-200-continent)
string

Continent name

Example:`North America`

[`region_state`](#resp-200-region-state)
string

Region name when available

Example:`Virginia`

[`city`](#resp-200-city)
string

City name when available

Example:`Alexandria`

[`postal_code`](#resp-200-postal-code)
string

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

Example:`22309`

[`timezone`](#resp-200-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](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

Example:`Europe/London`

[`raw_offset`](#resp-200-raw-offset)
integer

The offset from utc in seconds

Example:`-18000`

[`dst_offset`](#resp-200-dst-offset)
integer

The daylight saving time offset in seconds

Example:`3600`

### Errors

#401

Unauthorized. Incorrect authentication credentials.

 

`application/json`

[`detail`](#err-401-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`](#err-403-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`](#err-429-detail)
string

Details for the Over Query Limit error message

Example:`The rate limit for this endpoint has been exceeded`

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

```javascript
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));
```

```python
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)
```

```json
{
  "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
}
```

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

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

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