Assets nearby a Geolocation

GET

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

Retrieve the stores nearby an ip location. Stores are returned only if a relevant ip location is found - for an accuracy of 20km or less.

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

limit

integer

To limit number of assets retrieved from an IP location.

Example: 10

query

string

Search query combining one or more search clauses. Each search clause is made up of three parts structured as field : operator value. , e.g. name:="My cool store"

Vocabulary

• Field: attribute of the Store that is searched, e.g. the attribute name of the store.

• Operator: test that is performed on the data to provide a match, e.g. =. Each field has a default operator. If none operator follow the :, the default one is used.

• Value: the content of the attribute that is tested, e.g. the name of the store "My cool store".

Combine clauses with the conjunctions AND or OR, and negate the query with NOT.

Fields

• type: An element is contained within type collection. e.g. type:"myType"

• tag: An element is contained within tag collection. e.g. tag:"myTag"

• city: text matching: the value match the city field. e.g. city:="Paris"

• country: text matching: the value match the countryCode field. e.g. country:="FR"

• name: text matching: the value match the name field. e.g. name:="myName"

• idstore: text matching: the value match the idstore field. e.g. idstore:="myIdStore"

• user: concerns all fields inside user_properties. text matching or numerical comparison. e.g. user.myAttribute:="myValue"

• localized: used for localizedNames to search in native language. text matching in collection: the value match one of the the localizedNames. e.g. localized:="centro"

userProperties field has no restriction regarding the data you can put in it (Arrays, Object, Boolean, String, Numeric...) but you can only query for text matching or numerical comparison.

Operators

• : : Default and mandatory operator. For type and tag fields, define that an element is contained within a collection.

• = : The content of a string or a number is equal to the other.

• > : A number is greater than another.

• < : A number is smaller than another.

• >= : A number is greater than or equal to another.

• <= : A number is smaller than or equal to another.

• AND : Return assets that match both clauses.

• OR : Return assets that match either clauses.

• NOT : Negates a search clause.

For compound clauses, you can use parentheses to group clauses together. For example: (type:"type1" OR type:"type2") AND tag:"hockey" You can use NOT operator to negates a search clause. For example: not type:"type1"

Example: name:'My cool store'|type:'click_and_collect'

Response

200 application/json

Geolocation and Stores successufully retrieved

stores

object

Assets Collection Response as a GeoJSon FeatureCollection with Asset properties

Example:

JSON

        
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "store_id": "2354",
        "name": "Berkeley Street/Berkeley Square",
        "contact": {
          "phone": "02076295779",
          "website": "https://www.starbucks.com/store-locator/store/2354/berkeley-street-berkeley-square-27-berkeley-st-berkeley-square-london-eng-w-1-x-5-"
        },
        "address": {
          "lines": [
            "27 Berkeley St",
            "London, ENG W1X 5AD"
          ],
          "country_code": "GB",
          "city": "London",
          "zipcode": "W1X 5AD"
        },
        "user_properties": {
          "take_away": "available"
        },
        "tags": [
          "WA",
          "WF",
          "CD",
          "DR",
          "XO"
        ],
        "types": [
          "Coffee shop"
        ],
        "last_updated": "2022-11-10T13:23:53.564829+00:00",
        "distance": 135.28682936,
        "open": {
          "open_now": true,
          "open_hours": [
            {
              "end": "18:00",
              "start": "06:30"
            }
          ],
          "week_day": 2,
          "current_slice": {
            "end": "18:00",
            "start": "06:30"
          }
        },
        "weekly_opening": {
          "1": {
            "hours": [
              {
                "end": "18:00",
                "start": "06:30"
              }
            ],
            "isSpecial": false
          },
          "2": {
            "hours": [
              {
                "end": "18:00",
                "start": "06:30"
              }
            ],
            "isSpecial": false
          },
          "3": {
            "hours": [
              {
                "end": "18:00",
                "start": "06:30"
              }
            ],
            "isSpecial": false
          },
          "4": {
            "hours": [
              {
                "end": "18:00",
                "start": "06:30"
              }
            ],
            "isSpecial": false
          },
          "5": {
            "hours": [
              {
                "end": "18:00",
                "start": "06:30"
              }
            ],
            "isSpecial": false
          },
          "6": {
            "hours": [
              {
                "end": "17:00",
                "start": "08:00"
              }
            ],
            "isSpecial": false
          },
          "7": {
            "hours": [
              {
                "end": "17:00",
                "start": "08:00"
              }
            ],
            "isSpecial": false
          },
          "timezone": "Europe/London"
        },
        "opening_hours": {
          "usual": {
            "1": [
              {
                "end": "18:00",
                "start": "06:30"
              }
            ],
            "2": [
              {
                "end": "18:00",
                "start": "06:30"
              }
            ],
            "3": [
              {
                "end": "18:00",
                "start": "06:30"
              }
            ],
            "4": [
              {
                "end": "18:00",
                "start": "06:30"
              }
            ],
            "5": [
              {
                "end": "18:00",
                "start": "06:30"
              }
            ],
            "6": [
              {
                "end": "17:00",
                "start": "08:00"
              }
            ],
            "7": [
              {
                "end": "17:00",
                "start": "08:00"
              }
            ]
          },
          "special": {},
          "timezone": "Europe/London"
        }
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -0.14408,
          51.5088
        ]
      }
    }
  ],
  "pagination": {
    "page": 1,
    "pageCount": 1
  }
}

    

Show 3 propertiesHide 3 properties

stores. type

string

the Geojson Type (only 'FeatureCollection')

Available options: FeatureCollection

stores. features

object[]

the Assets Features

Show 3 propertiesHide 3 properties

stores.features. type

string

the Geojson Type (only 'Feature')

Available options: Feature

stores.features. properties

object

Attributes describing an Asset.

Show 12 propertiesHide 12 properties

stores.features.properties. name

string

The asset's name.

Example: My Cool Store

stores.features.properties. store_id

string

A textual identifier that uniquely identifies an Asset. It must matches the following regexp [A-Za-z0-9]+

Example: STORE_ID_12345

stores.features.properties. address

object

An object containing the separate components applicable to this address.

Example:

JSON

        
{
  "lines": [
    "8 Southwark St"
  ],
  "country_code": "UK",
  "city": "London",
  "zipcode": "SE1 1TL"
}

    

Show 4 propertiesHide 4 properties

stores.features.properties.address. lines

string[]

An Array for lines of an Asset Address

Example:

JSON

        
[
  "Building Centre",
  "26 Store Street"
]

    

stores.features.properties.address. country_code

string | null

An ISO_3166-1 Country Code where the Asset is located (see https://en.wikipedia.org/wiki/ISO_3166-1 for full list)

Example: UK

stores.features.properties.address. city

string

A City where belongs an Asset

Example: London

stores.features.properties.address. zipcode

string

An Zipcode / Postal code of an Asset Address

Example: WC1E 7BT

stores.features.properties. contact

object

An object containing the asset's contact available information.

Example:

JSON

        
{
  "website": "https://www.woosmap.com",
  "phone": "+44 20 7693 4000",
  "email": "[email protected]"
}

    

Show 3 propertiesHide 3 properties

stores.features.properties.contact. website

string

The website contact for this Asset, such as a business' homepage.

Example: https://www.woosmap.com

stores.features.properties.contact. phone

string

Contains the Asset's phone number in its local format.

Example: +44 20 7693 4000

stores.features.properties.contact. email

string

Contains the Asset's email contact.

Example: [email protected]

stores.features.properties. open

object

The Current opening status for an Asset

Example:

JSON

        
{
  "open_now": true,
  "open_hours": [
    {
      "end": "20:00",
      "start": "05:00"
    }
  ],
  "week_day": 1,
  "current_slice": {
    "end": "20:00",
    "start": "05:00"
  }
}

    

Show 5 propertiesHide 5 properties

stores.features.properties.open. current_slice

object

The hours for an opening period. To define a slice of time where the asset is open you must define a start and end keys. start and end must belong to the same day (crossing midnight may result in open_now being always false.)

Example:

JSON

        
{
  "start": "08:30",
  "end": "19:30"
}

    

Show 2 propertiesHide 2 properties

stores.features.properties.open.current_slice. start

string required

Contains a time of day in 24-hour hh:mm format for the begin of opening period. Values are in the range 00:00–23:59

Example: 08:30

stores.features.properties.open.current_slice. end

string required

Contains a time of day in 24-hour hh:mm format for the end of opening period. Values are in the range 00:00–23:59

Example: 19:30

stores.features.properties.open. open_hours

object[]

the opening hours for the day

Show 2 propertiesHide 2 properties

stores.features.properties.open.open_hours. start

string required

Contains a time of day in 24-hour hh:mm format for the begin of opening period. Values are in the range 00:00–23:59

Example: 08:30

stores.features.properties.open.open_hours. end

string required

Contains a time of day in 24-hour hh:mm format for the end of opening period. Values are in the range 00:00–23:59

Example: 19:30

stores.features.properties.open. open_now

boolean

Boolean value indicating the status of the opening hours

stores.features.properties.open. next_opening

object

the next opening hours period

Show 3 propertiesHide 3 properties

stores.features.properties.open.next_opening. end

string

the hours of next opening

Example: 17:30

stores.features.properties.open.next_opening. start

string

the hours of next closing

Example: 06:00

stores.features.properties.open.next_opening. day

string

the day of next opening

Example: 2021-11-16

stores.features.properties.open. week_day

integer

the day of the week starting from 1 to 7

stores.features.properties. weekly_opening

object

The current Weekly Opening taking into account the special hours

Example:

JSON

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

    

Show 8 propertiesHide 8 properties

stores.features.properties.weekly_opening. 1

object

The opening Hours for Monday

Example:

JSON

        
{
  "hours": [
    {
      "start": "06:30",
      "end": "18:00"
    }
  ],
  "isSpecial": false
}

    

Show 2 propertiesHide 2 properties

stores.features.properties.weekly_opening.1. hours

object[]

Show 2 propertiesHide 2 properties

stores.features.properties.weekly_opening.1.hours. start

string required

Contains a time of day in 24-hour hh:mm format for the begin of opening period. Values are in the range 00:00–23:59

Example: 08:30

stores.features.properties.weekly_opening.1.hours. end

string required

Contains a time of day in 24-hour hh:mm format for the end of opening period. Values are in the range 00:00–23:59

Example: 19:30

stores.features.properties.weekly_opening.1. isSpecial

boolean

Define if the hours comes from a special opening hours day.

Example: false

stores.features.properties.weekly_opening. 2

object

The opening Hours for Monday

Example:

JSON

        
{
  "hours": [
    {
      "start": "06:30",
      "end": "18:00"
    }
  ],
  "isSpecial": false
}

    

Show 2 propertiesHide 2 properties

stores.features.properties.weekly_opening.2. hours

object[]

Show 2 propertiesHide 2 properties

stores.features.properties.weekly_opening.2.hours. start

string required

Contains a time of day in 24-hour hh:mm format for the begin of opening period. Values are in the range 00:00–23:59

Example: 08:30

stores.features.properties.weekly_opening.2.hours. end

string required

Contains a time of day in 24-hour hh:mm format for the end of opening period. Values are in the range 00:00–23:59

Example: 19:30

stores.features.properties.weekly_opening.2. isSpecial

boolean

Define if the hours comes from a special opening hours day.

Example: false

stores.features.properties.weekly_opening. 3

object

The opening Hours for Monday

Example:

JSON

        
{
  "hours": [
    {
      "start": "06:30",
      "end": "18:00"
    }
  ],
  "isSpecial": false
}

    

Show 2 propertiesHide 2 properties

stores.features.properties.weekly_opening.3. hours

object[]

Show 2 propertiesHide 2 properties

stores.features.properties.weekly_opening.3.hours. start

string required

Contains a time of day in 24-hour hh:mm format for the begin of opening period. Values are in the range 00:00–23:59

Example: 08:30

stores.features.properties.weekly_opening.3.hours. end

string required

Contains a time of day in 24-hour hh:mm format for the end of opening period. Values are in the range 00:00–23:59

Example: 19:30

stores.features.properties.weekly_opening.3. isSpecial

boolean

Define if the hours comes from a special opening hours day.

Example: false

stores.features.properties.weekly_opening. 4

object

The opening Hours for Monday

Example:

JSON

        
{
  "hours": [
    {
      "start": "06:30",
      "end": "18:00"
    }
  ],
  "isSpecial": false
}

    

Show 2 propertiesHide 2 properties

stores.features.properties.weekly_opening.4. hours

object[]

Show 2 propertiesHide 2 properties

stores.features.properties.weekly_opening.4.hours. start

string required

Contains a time of day in 24-hour hh:mm format for the begin of opening period. Values are in the range 00:00–23:59

Example: 08:30

stores.features.properties.weekly_opening.4.hours. end

string required

Contains a time of day in 24-hour hh:mm format for the end of opening period. Values are in the range 00:00–23:59

Example: 19:30

stores.features.properties.weekly_opening.4. isSpecial

boolean

Define if the hours comes from a special opening hours day.

Example: false

stores.features.properties.weekly_opening. 5

object

The opening Hours for Monday

Example:

JSON

        
{
  "hours": [
    {
      "start": "06:30",
      "end": "18:00"
    }
  ],
  "isSpecial": false
}

    

Show 2 propertiesHide 2 properties

stores.features.properties.weekly_opening.5. hours

object[]

Show 2 propertiesHide 2 properties

stores.features.properties.weekly_opening.5.hours. start

string required

Contains a time of day in 24-hour hh:mm format for the begin of opening period. Values are in the range 00:00–23:59

Example: 08:30

stores.features.properties.weekly_opening.5.hours. end

string required

Contains a time of day in 24-hour hh:mm format for the end of opening period. Values are in the range 00:00–23:59

Example: 19:30

stores.features.properties.weekly_opening.5. isSpecial

boolean

Define if the hours comes from a special opening hours day.

Example: false

stores.features.properties.weekly_opening. 6

object

The opening Hours for Monday

Example:

JSON

        
{
  "hours": [
    {
      "start": "06:30",
      "end": "18:00"
    }
  ],
  "isSpecial": false
}

    

Show 2 propertiesHide 2 properties

stores.features.properties.weekly_opening.6. hours

object[]

Show 2 propertiesHide 2 properties

stores.features.properties.weekly_opening.6.hours. start

string required

Contains a time of day in 24-hour hh:mm format for the begin of opening period. Values are in the range 00:00–23:59

Example: 08:30

stores.features.properties.weekly_opening.6.hours. end

string required

Contains a time of day in 24-hour hh:mm format for the end of opening period. Values are in the range 00:00–23:59

Example: 19:30

stores.features.properties.weekly_opening.6. isSpecial

boolean

Define if the hours comes from a special opening hours day.

Example: false

stores.features.properties.weekly_opening. 7

object

The opening Hours for Monday

Example:

JSON

        
{
  "hours": [
    {
      "start": "06:30",
      "end": "18:00"
    }
  ],
  "isSpecial": false
}

    

Show 2 propertiesHide 2 properties

stores.features.properties.weekly_opening.7. hours

object[]

Show 2 propertiesHide 2 properties

stores.features.properties.weekly_opening.7.hours. start

string required

Contains a time of day in 24-hour hh:mm format for the begin of opening period. Values are in the range 00:00–23:59

Example: 08:30

stores.features.properties.weekly_opening.7.hours. end

string required

Contains a time of day in 24-hour hh:mm format for the end of opening period. Values are in the range 00:00–23:59

Example: 19:30

stores.features.properties.weekly_opening.7. isSpecial

boolean

Define if the hours comes from a special opening hours day.

Example: false

stores.features.properties.weekly_opening. 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

stores.features.properties. types

string[]

Contains an array of types describing the Asset.

Example:

JSON

        
[
  "drive",
  "click_and_collect"
]

    

stores.features.properties. tags

string[]

Contains an array of tags describing the Asset. For example a list of available amenities.

Example:

JSON

        
[
  "wifi",
  "covered_parking"
]

    

stores.features.properties. last_updated

string | null

the previous date timestamp when the asset has been updated

Example: 2022-11-08T15:48:08.556803+00:00

stores.features.properties. user_properties

object | null

Contains all additional information relative to an Asset. If not set it returns null value.

Example:

JSON

        
{
  "some_user_properties": "some_value"
}

    

stores.features.properties. opening_hours

object | null

An object describing the opening hours of an Asset.

Example:

JSON

        
{
  "timezone": "Europe/London",
  "usual": {
    "1": [],
    "default": [
      {
        "start": "08:30",
        "end": "22:00"
      }
    ]
  },
  "special": {
    "2015-02-07": [
      {
        "start": "08:00",
        "end": "23:00"
      }
    ]
  }
}

    

Show 3 propertiesHide 3 properties

stores.features.properties.opening_hours. 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

stores.features.properties.opening_hours. usual

object

An object describing the usual opening hours of an Asset.

Show 8 propertiesHide 8 properties

stores.features.properties.opening_hours.usual. 1

object[]

The opening Hours for Monday

Show 2 propertiesHide 2 properties

stores.features.properties.opening_hours.usual.1. start

string required

Contains a time of day in 24-hour hh:mm format for the begin of opening period. Values are in the range 00:00–23:59

Example: 08:30

stores.features.properties.opening_hours.usual.1. end

string required

Contains a time of day in 24-hour hh:mm format for the end of opening period. Values are in the range 00:00–23:59

Example: 19:30

stores.features.properties.opening_hours.usual. 2

object[]

The opening Hours for Tuesday

Show 2 propertiesHide 2 properties

stores.features.properties.opening_hours.usual.2. start

string required

Contains a time of day in 24-hour hh:mm format for the begin of opening period. Values are in the range 00:00–23:59

Example: 08:30

stores.features.properties.opening_hours.usual.2. end

string required

Contains a time of day in 24-hour hh:mm format for the end of opening period. Values are in the range 00:00–23:59

Example: 19:30

stores.features.properties.opening_hours.usual. 3

object[]

The opening Hours for Wednesday

Show 2 propertiesHide 2 properties

stores.features.properties.opening_hours.usual.3. start

string required

Contains a time of day in 24-hour hh:mm format for the begin of opening period. Values are in the range 00:00–23:59

Example: 08:30

stores.features.properties.opening_hours.usual.3. end

string required

Contains a time of day in 24-hour hh:mm format for the end of opening period. Values are in the range 00:00–23:59

Example: 19:30

stores.features.properties.opening_hours.usual. 4

object[]

The opening Hours for Thursday

Show 2 propertiesHide 2 properties

stores.features.properties.opening_hours.usual.4. start

string required

Contains a time of day in 24-hour hh:mm format for the begin of opening period. Values are in the range 00:00–23:59

Example: 08:30

stores.features.properties.opening_hours.usual.4. end

string required

Contains a time of day in 24-hour hh:mm format for the end of opening period. Values are in the range 00:00–23:59

Example: 19:30

stores.features.properties.opening_hours.usual. 5

object[]

The opening Hours for Friday

Show 2 propertiesHide 2 properties

stores.features.properties.opening_hours.usual.5. start

string required

Contains a time of day in 24-hour hh:mm format for the begin of opening period. Values are in the range 00:00–23:59

Example: 08:30

stores.features.properties.opening_hours.usual.5. end

string required

Contains a time of day in 24-hour hh:mm format for the end of opening period. Values are in the range 00:00–23:59

Example: 19:30

stores.features.properties.opening_hours.usual. 6

object[]

The opening Hours for Saturday

Show 2 propertiesHide 2 properties

stores.features.properties.opening_hours.usual.6. start

string required

Contains a time of day in 24-hour hh:mm format for the begin of opening period. Values are in the range 00:00–23:59

Example: 08:30

stores.features.properties.opening_hours.usual.6. end

string required

Contains a time of day in 24-hour hh:mm format for the end of opening period. Values are in the range 00:00–23:59

Example: 19:30

stores.features.properties.opening_hours.usual. 7

object[]

The opening Hours for Sunday

Show 2 propertiesHide 2 properties

stores.features.properties.opening_hours.usual.7. start

string required

Contains a time of day in 24-hour hh:mm format for the begin of opening period. Values are in the range 00:00–23:59

Example: 08:30

stores.features.properties.opening_hours.usual.7. end

string required

Contains a time of day in 24-hour hh:mm format for the end of opening period. Values are in the range 00:00–23:59

Example: 19:30

stores.features.properties.opening_hours.usual. default

object[]

Contains the default opening hours to apply to all week days

Show 2 propertiesHide 2 properties

stores.features.properties.opening_hours.usual.default. start

string required

Contains a time of day in 24-hour hh:mm format for the begin of opening period. Values are in the range 00:00–23:59

Example: 08:30

stores.features.properties.opening_hours.usual.default. end

string required

Contains a time of day in 24-hour hh:mm format for the end of opening period. Values are in the range 00:00–23:59

Example: 19:30

stores.features.properties.opening_hours. special

object

An object describing the special opening hours of an Asset.

Show 2 propertiesHide 2 properties

stores.features.properties.opening_hours.special. 2015-02-07

object[]

The format for defining opening and closing hours for a particular day is the same as the usual. Instead of using numeric week day for keys you must use a date YYYY-MM-DD like "2015-03-08" (see ISO-8601).

Show 2 propertiesHide 2 properties

stores.features.properties.opening_hours.special.2015-02-07. start

string required

Contains a time of day in 24-hour hh:mm format for the begin of opening period. Values are in the range 00:00–23:59

Example: 08:30

stores.features.properties.opening_hours.special.2015-02-07. end

string required

Contains a time of day in 24-hour hh:mm format for the end of opening period. Values are in the range 00:00–23:59

Example: 19:30

stores.features.properties.opening_hours.special. 2015-02-08

object[]

Show 2 propertiesHide 2 properties

stores.features.properties.opening_hours.special.2015-02-08. start

string required

Contains a time of day in 24-hour hh:mm format for the begin of opening period. Values are in the range 00:00–23:59

Example: 08:30

stores.features.properties.opening_hours.special.2015-02-08. end

string required

Contains a time of day in 24-hour hh:mm format for the end of opening period. Values are in the range 00:00–23:59

Example: 19:30

stores.features.properties. distance

number

The distance in meters from the geolocated position or searched position if exist

Example: 544.581

stores.features. geometry

object

GeoJSon Point Geometry

Example:

JSON

        
{
  "type": "Point",
  "coordinates": [
    -0.14408,
    51.5088
  ]
}

    

Show 2 propertiesHide 2 properties

stores.features.geometry. type

string

the geometry type

Available options: Point

stores.features.geometry. coordinates

number[]

An array of comma separated {latitude,longitude} strings.

Example:

JSON

        
[
  43.4,
  -2.1
]

    

stores. pagination

object

Pagination to reach all returned assets. max 300 assets par page.

Show 2 propertiesHide 2 properties

stores.pagination. page

integer

the request page

Example: 1

stores.pagination. pageCount

integer

the number of available pages

Example: 10

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/stores?private_key=YOUR_PRIVATE_API_KEY&ip_address=173.79.254.254&limit=1'

    

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

    

        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)


    

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,
  "stores": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "properties": {
          "store_id": "STORE_ID_123456",
          "name": "My Cool Store",
          "contact": {
            "email": "[email protected]",
            "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
    }
  }
}

    

        
{
  "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!