Generic Search

Required Permission

can-search-locations

See Auth* (scopes).

Request

GET /locations?<query string>

Parameters

Parameter Example Default Type Description
correlation_id 9180b450-1e4c-4dd1-b0e5-37d0bfaaf185 - string identifier for request tracking
ret 6f3c2d96-fccb-46f5-9dd7-7e0a478dfdfd - uuid retailer id (*1)
location_provider_id e8ec5293-449b-45e5-9435-cd90ca942e3a - uuid location provider id
consolidator_id 40251966-8252-41aa-a888-1f1953fe27d5 - uuid consolidator id
store_id 1234 - string store (external) id
lon -0.1274 - signed floating point longitude
lat 51.5197 - signed floating point latitude
postcode N19 1AA - string postcode
countrycode GBR - ISO 3166-1 country code (*2) country code
radius 10000 1000 integer radius
include_own_stores true true boolean include own stores?
own_stores false false boolean own stores only
own_stores_qty 1 3 integer number of closest own stores to retrieve (beyond radius)
pudo_qty 1 0 integer number of pudos + own stores to retrieve (beyond radius)
multi_country true false boolean should include locations from multiple countries (*3)
language en - string prefer location data in this language (*4)

Notes

  1. Manually generated and provided by Metapack for each retailer.
  2. Valid 3 digit, 2 characters or 3 characters.
  3. Different to the one specified via the countrycode parameter.
  4. Must be a valid lowercase ISO 639-1 two-letter code (see)

Syntax Diagram

Some of the parameters are mutually exclusive (e.g. lat + lon / postcode + countrycode).

  1. Search by location provider
    1. Retrieve all locations optionally filtered by country (*1)
    2. Retrieve a list of locations given the location provider internal id (store id) and optionally, a unique one, given the country code (*2)
    3. Radius search for active locations, given the radius value and geo-coordinates for the center (*3)
  2. Search active locations
    1. Search own stores above radius (*4) (*5)
    2. Search all locations configured for the retailer (*6) (*7)
      1. Filter by location provider, according to configuration on Location Services (*8) (*9)
      2. Filter by consolidator, according to configuration on Location Services (*10) (*11)
  3. Search by consolidator
    1. Retrieve all locations optionally filtered by country (*12)
    2. Radius search for active locations, given the radius value and geo-coordinates for the center (*13)

Examples

  1. GET /locations?location_provider_id=<...>[&countrycode=<...>]
  2. GET /locations?location_provider_id=<...>&store_id=<...>[&countrycode=<...>]
  3. GET /locations?location_provider_id=<...>&lat=<latitude>&lon=<longitude>[&radius=<radius in meters>]
  4. GET /locations?ret=<retailer id>&lat=<latitude>&lon=<longitude>&own_stores=true[&own_stores_qty=<number of stores to retrieve>][&multi_country=<...>][&radius=<minimum distance from center>]
  5. GET /locations?ret=<...>&postcode=<...>&countrycode=<...>&own_stores=true[&own_stores_qty=<number of stores to retrieve>][&multi_country=<...>][&radius=<minimum distance from center>]
  6. GET /locations?ret=<...>&lat=<latitude>&lon=<longitude>[&countrycode=<...>][&include_own_stores=<...>][&multi_country=<...>][&radius=<...>]
  7. GET /locations?ret=<...>&postcode=<...>&countrycode=<...>[&include_own_stores=<...>][&multi_country=<...>][&radius=<...>]
  8. GET /locations?ret=<...>&lat=<latitude>&lon=<longitude>&countrycode=<...>&location_provider_id=<...>[&include_own_stores=<...>][&multi_country=<...>][&radius=<...>]
  9. GET /locations?ret=<...>&postcode=<...>&countrycode=<...>&location_provider_id=<...>[&include_own_stores=<...>][&multi_country=<...>][&radius=<...>]
  10. GET /locations?ret=<...>&lat=<latitude>&lon=<longitude>&countrycode=<...>&consolidator_id=<...>[&include_own_stores=<...>][&multi_country=<...>][&radius=<...>]
  11. GET /locations?ret=<...>&postcode=<...>&countrycode=<...>&consolidator_id=<...>[&include_own_stores=<...>][&multi_country=<...>][&radius=<...>]
  12. GET /locations?consolidator_id=<...>[&countrycode=<...>]
  13. GET /locations?consolidator_id=<...>&lat=<latitude>&lon=<longitude>[&radius=<radius in meters>]

The following diagram lists all of the valid combinations of parameters. Read from left to right, choosing a single path; loops represent optional parameters; forks represent alternatives; a parameter may appear more than once in which case, ignore the subsequent ocurrences if already added:

Syntax Diagram

locations
         ::= location_provider_id ( store_id countrycode? language?| lon lat radius  language?| countrycode? )
           | ret ( lon lat | countrycode postcode ) ( own_stores own_stores_qty? | pudo_qty ) ( countrycode | countrycode? location_provider_id? include_own_stores? ) consolidator_id? multi_country? radius? language?
           | consolidator_id ( lon lat radius? language?| countrycode? )

Response

HTTP/1.1 200 OK
[
  {
    "storeId": "0002",
    "storeName": "MetaPack Limited",
    "city": "London",
    "postCode": "WC1X 8XZ",
    "countryCode": "GBR",
    "address": "201 Gray’s Inn Road",
    "latitude": 51.523402,
    "longitude": -0.114333,
    "telephoneNumber": "+442078436720",
    "email": "mkstore@askjeeves.com",
    "logoUrl": null,
    "photoUrls": [],
    "hasDisabledAccess": false,
    "description": null,
    "id": "ec30cb2b-9c64-46ee-a6b4-2db3238901d9",
    "tags": [
       "potato",
       "pharmacy",
       "refrigeration"
    ],
    "locationProvider": {
      "id": "ca0e1f97-dc57-4df5-9430-c93264603197",
      "name": "DoDo Test",
      "ownStores": false
    },
    "links": [
      {
        "rel": "self",
        "href": "/locations/ec30cb2b-9c64-46ee-a6b4-2db3238901d9"
      },
      {
        "rel": "openingTimesRules",
        "href": "/locations/ec30cb2b-9c64-46ee-a6b4-2db3238901d9/openingTimesRules"
      },
     {
        "rel": "customData",
        "href": "/locations/ec30cb2b-9c64-46ee-a6b4-2db3238901d9/customData"
       }
    ]
  }
]

Failure

Invalid parameter combination or data types submitted:

HTTP/1.1 400 BAD REQUEST

User doesn't have the required permission:

HTTP/1.1 403 FORBIDDEN

Retailer or location provider does not exist:

HTTP/1.1 404 NOT FOUND

Other errors:

HTTP/1.1 500 INTERNAL SERVER ERROR

results matching ""

    No results matching ""