Source: https://developers.woosmap.com/products/geolocation-api/location/

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

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

# Get User's Device Location



## Overview

Woosmap Geolocation API can provide the location of your users thanks to IP address of their devices. You can query the API using a public or a private key according to your use case and calls origins.

### Client-side requests

For client-side requests, use your public key (parameter `key`) related to your project. The IP address to geocode is the public IP from the user device.

### Server-side requests

For server-side requests, get the position of a specific ip address using a `private_key` in your requests and parameter `ip_address` to geolocate.

## Optional parameters

```plaintext
https://api.woosmap.com/geolocation/position/?private_key={PRIVATE_API_KEY}&cc_format=alpha2
```

#### cc\_format

To specify the [country code](https://en.wikipedia.org/wiki/ISO_3166-1) format returned in the response. Default is `alpha2`.

Available `cc_format` values are `alpha2` or `alpha3`.

## Geolocation example

The following example requests the geolocation of a specific IP address `173.79.254.254` on the server-side:

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

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

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

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

```javascript
const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: 'https://api.woosmap.com/geolocation/position?private_key=YOUR_PRIVATE_API_KEY&ip_address=173.79.254.254',
  headers: { }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});
```

```java
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("https://api.woosmap.com/geolocation/position?private_key=YOUR_PRIVATE_API_KEY&ip_address=173.79.254.254")
  .method("GET", body)
  .build();
Response response = client.newCall(request).execute();
```

```ruby
require "uri"
require "net/http"

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

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)

response = https.request(request)
puts response.read_body
```

## Response

For a provided location, the response is a formatted JSON containing the keys:

| `country_code` | ISO 3166-1 Alpha-2 or Alpha-3 compatible country code |
| `country_name` | country name (string value) |
| `continent` | continent name (string value) |
| `region_state` | region name when available (string value) |
| `city` | city name (string value) when available |
| `postal_code` | a postal code close to the user’s location, when available |
| `latitude` `longitude` | approximate latitude and longitude of the geographical area associated with the IP address |
| `accuracy` | radius in kilometers around the specified location where the IP address is likely to be |
| `viewport` | geographic bounds (northeast latlng and southwest latlng) build from latitude, longitude and accuracy values, to help center a map |
| `timezone` | the time zone associated with location, as specified by the IANA Time Zone Database |
| `raw_offset` | the offset from the Coordinated Universal Time (UTC) in seconds |
| `dst_offset` | the Daylight Saving Time (DST) offset in seconds |

According to IP data relevance and accuracy some keys may eventually not be provided.

```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,
}
```

## Your IP address Example

Here is a sample of a Geolocation API call using Javascript. The fetched location is used to display a map.

https://demo.woosmap.com/js-samples/samples/geolocation-api/app/dist/
[](https://demo.woosmap.com/js-samples/samples/geolocation-api/highlight/highlight.html "Open in new tab with highlighted code")
Try sample 

- [CodeSandbox](https://codesandbox.io/p/devbox/github/woosmap/js-samples/tree/master/dist/samples/geolocation-api/app?file=index.ts)
- [JsFiddle](https://jsfiddle.net/gh/get/library/pure/woosmap/js-samples/tree/master/dist/samples/geolocation-api/jsfiddle)
- [Clone on Github](https://github.com/Woosmap/js-samples/tree/sample/geolocation-api)

## Usage limits

The following usage limits are in place for the `/position` endpoint of Geolocation API:

If a Public Key is used

- Maximum of 50 queries per second (QPS) per requesting IP

If a Private Key is used

- Maximum of 50 queries per second (QPS) per unique enduser’s IP passed in parameter