Source: https://developers.woosmap.com/products/geolocation-api/stores/ > For clean Markdown of any page, append `.md` to the page URL. > For a complete documentation index, see https://developers.woosmap.com/llms.txt # Search Stores Nearby a User's Device Location **Minimum acceptable accuracy** Stores are retrieved only for an accuracy of 20km or less. ## Overview This API endpoint allows you to retrieve the stores nearby an ip location. Stores are returned only if a relevant ip location is found. **Minimum acceptable accuracy** For narrowing down the nearby stores, please refer to the [Stores API](/products/stores-api/features/search/) as this endpoint accepts the same parameters (e.g. `radius`). You can query the API using your public or 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/stores/?private_key={PRIVATE_API_KEY}&radius=10000&&limit=10 ``` #### limit In addition to optional parameters from the [Store Search Endpoint](/products/stores-api/features/search/) you can specify a `limit` value to limit number of assets to retrieve from an IP location (`integer` value) #### 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`. ## Stores nearby Geolocation example The following example requests the closest store nearby 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/stores?private_key=YOUR_PRIVATE_API_KEY&ip_address=173.79.254.254&limit=1", requestOptions) .then((response) => response.text()) .then((result) => console.log(result)) .catch((error) => console.error(error)); ``` ```shell curl -L 'https://api.woosmap.com/geolocation/stores?private_key=YOUR_PRIVATE_API_KEY&ip_address=173.79.254.254&limit=1' ``` ```python import requests url = "https://api.woosmap.com/geolocation/stores?private_key=YOUR_PRIVATE_API_KEY&ip_address=173.79.254.254&limit=1" payload = {} headers = {} response = requests.request("GET", url, headers=headers, data=payload) print(response.text) ``` ```text https://api.woosmap.com/geolocation/stores ?ip_address=173.79.254.254 &limit=1 &private_key=YOUR_PRIVATE_API_KEY ``` ```javascript const axios = require('axios'); let config = { method: 'get', maxBodyLength: Infinity, url: 'https://api.woosmap.com/geolocation/stores?private_key=YOUR_PRIVATE_API_KEY&ip_address=173.79.254.254&limit=1', 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/stores?private_key=YOUR_PRIVATE_API_KEY&ip_address=173.79.254.254&limit=1") .method("GET", body) .build(); Response response = client.newCall(request).execute(); ``` ```ruby require "uri" require "net/http" url = URI("https://api.woosmap.com/geolocation/stores?private_key=YOUR_PRIVATE_API_KEY&ip_address=173.79.254.254&limit=1") 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 The Response is a formated JSON containing the keys: `country_code, country_name, continent, city, region_state, postal_code, timezone, raw_offset, dst_offset`. See the [Get Location](/products/geolocation-api/location/#response) endpoint documentation for more details on those keys. According to IP data relevance, JSON can contain the device location and nearby stores (based on your `query`) ```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, "stores": { "type": "FeatureCollection", "features": [ { "type": "Feature", "properties": { "store_id": "STORE_ID_123456", "name": "My Cool Store", "contact": { "email": "contact@woosmap.com", "phone": "+44 20 7693 4000", "website": "https://www.woosmap.com", }, "address": { "lines": ["Building Centre", "26 Store Street"], "country_code": "UK", "city": "London", "zipcode": "WC1E 7BT", }, "user_properties": { "some_user_properties": "associated user value" }, "tags": ["wifi", "covered_parking"], "types": ["drive", "click_and_collect"], "last_updated": "2025-09-16T08:49:42.523114+00:00", "distance": 0, "open": { "open_now": true, "open_hours": [{ "end": "22:00", "start": "08:30" }], "week_day": 2, "current_slice": { "end": "22:00", "start": "08:30" }, }, "weekly_opening": { "1": { "hours": [], "isSpecial": false }, "2": { "hours": [{ "end": "22:00", "start": "08:30" }], "isSpecial": false, }, "3": { "hours": [{ "end": "22:00", "start": "08:30" }], "isSpecial": false, }, "4": { "hours": [{ "end": "22:00", "start": "08:30" }], "isSpecial": false, }, "5": { "hours": [{ "end": "22:00", "start": "08:30" }], "isSpecial": false, }, "6": { "hours": [{ "end": "22:00", "start": "08:30" }], "isSpecial": false, }, "7": { "hours": [{ "end": "22:00", "start": "08:30" }], "isSpecial": false, }, "timezone": "Europe/London", }, "opening_hours": { "usual": { "1": [], "default": [{ "end": "22:00", "start": "08:30" }], }, "special": { "2015-02-07": [{ "end": "23:00", "start": "08:00" }] }, "timezone": "Europe/London", }, }, "geometry": { "type": "Point", "coordinates": [-77.1067, 38.719] }, }, ], "pagination": { "page": 1, "pageCount": 2 }, }, } ``` ## Example using your IP Address https://demo.woosmap.com/js-samples/samples/geolocation-nearby-stores/app/dist/ [](https://demo.woosmap.com/js-samples/samples/geolocation-nearby-stores/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-nearby-stores/app?file=index.ts) - [JsFiddle](https://jsfiddle.net/gh/get/library/pure/woosmap/js-samples/tree/master/dist/samples/geolocation-nearby-stores/jsfiddle) - [Clone on Github](https://github.com/Woosmap/js-samples/tree/sample/geolocation-nearby-stores) ## Usage limits The following usage limits are in place for the `/stores` 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