Stores Resource (Shop API 15.1)

Summary

Http Method Resource Description
GET /Stores

This resource retrieves a list of stores, for the given site, that are within a configured distance of a location on the earth. The stores and their distance from the specified location are returned as a result set of Store objects. The distance is interpreted either in miles or kilometers depending on the "distance_unit" input parameter.

The location can be specified by either directly providing a latitude/longitude coordinate pair or by providing a country and a postal code:

  • If a postal code is passed, the resource looks in the system's geolocation mappings to find the coordinates for this postal code. If no matching geolocation is found, the resource will return an empty list of stores.
  • If coordinates are passed, the values for country and postal code are ignored.
GET /Stores/({Id},...,{Id}) To access multiple stores, you construct a URL using the template shown below. This template requires you to specify a store id. In the response, the server returns a corresponding store document.
GET /Stores/{Id} To access a store, you construct a URL using the template shown below. This template requires you to specify a store id. In the response, the server returns a corresponding store document.

Get Nearest Stores

This resource retrieves a list of stores, for the given site, that are within a configured distance of a location on the earth. The stores and their distance from the specified location are returned as a result set of Store objects. The distance is interpreted either in miles or kilometers depending on the "distance_unit" input parameter.

The location can be specified by either directly providing a latitude/longitude coordinate pair or by providing a country and a postal code:

Url

GET http://hostname:port/dw/shop/v15_1/stores?latitude={Decimal}&longitude={Decimal}&country_code={String}&postal_code={String}&distance_unit={String}&max_distance={Decimal}&start={Integer}&count={Integer}

Formats

json, xml

Authentication

Name Description
None No authentication.

Response Document

StoreResult

Query Parameters

Parameter Type Description Constraints
count Integer The maximum number of instances per request. Default value is 25. maxIntegerValue=200, minIntegerValue=1
country_code String The two letter ISO country code e.g. "US". maxLength=2, minLength=2
distance_unit String The distance unit. Supported values are "mi" and "km" (for miles and kilometers respectively, default is "km").  
latitude Decimal The geo coordinate latitude to search for stores (value range -90.00 .. 90.00). maxNumberValue=90.0, minNumberValue=-90.0
longitude Decimal The geo coordinate longitude to search for stores (value range -180.00 .. 180.00). maxNumberValue=180.0, minNumberValue=-180.0
max_distance Decimal The area (radius) in distancUnit where stores will be searched for (default is half of the earth's perimeter). maxNumberValue=20012.0, minNumberValue=0.0
postal_code String The postal code e.g. "01801". maxLength=10, minLength=3
start Integer The result set index to return the first instance for. Default value is 0. minIntegerValue=0

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 ConstraintViolationException

mp (MethodParameter)

o (Object)

reason (String)

Thrown if any request parameter value constraint is violated.

Sample

REQUEST:
GET /dw/shop/v15_1/stores?country_code=US&postal_code=02108&distance_unit=mi&max_distance=10.00&start=0&count=4 HTTP/1.1
Host: example.com
Accept: application/json

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=900,must-revalidate
Content-Length: 1328

{
  "_v" : "15.1",
  "count" : 4,
  "data" : [ {
    "address1" : "333 Washington St",
    "city" : "Boston",
    "country_code" : "US",
    "distance" : 0.0,
    "distance_unit" : "mi",
    "email" : "[email protected]",
    "id" : "store10",
    "name" : "Downtown TV Shop",
    "phone" : "+1-617-695-1565",
    "postal_code" : "02108",
    "state_code" : "MA"
  }, {
    "address1" : "1001 Cambridge St",
    "city" : "Cambridge",
    "country_code" : "US",
    "distance" : 1.41,
    "distance_unit" : "mi",
    "email" : "[email protected]",
    "id" : "store4",
    "name" : "Champaign Electronic Shop",
    "phone" : "+1-617-714-2640",
    "postal_code" : "02141",
    "state_code" : "MA"
  }, {
    "address1" : "584 Columbus Ave",
    "city" : "Boston",
    "country_code" : "US",
    "distance" : 1.94,
    "distance_unit" : "mi",
    "id" : "store5",
    "name" : "Short Electro",
    "phone" : "+1-617-888-7276",
    "postal_code" : "02118",
    "state_code" : "MA"
  }, {
    "address1" : "363 Hancock St",
    "city" : "North Quincy",
    "country_code" : "US",
    "distance" : 6.56,
    "distance_unit" : "mi",
    "email" : "[email protected]",
    "id" : "store3",
    "name" : "Wire-Wire",
    "phone" : "+1-617-318-2860",
    "postal_code" : "02171",
    "state_code" : "MA"
  } ],
  "next" : "http://example.com/dw/shop/v15_1/stores?count=4&start=4&country_code=US&postal_code=02108&distance_unit=mi&max_distance=10.00&client_id=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "start" : 0,
  "total" : 8
}

Get Multiple Stores

To access multiple stores, you construct a URL using the template shown below. This template requires you to specify a store id. In the response, the server returns a corresponding store document.

Url

GET http://hostname:port/dw/shop/v15_1/stores/({id},...,{id})

Formats

json, xml

Authentication

Name Description
None No authentication.

Response Document

StoreResult

Path Parameters

Parameter Type Description Constraints
ids [String] The ids of the requested stores. maxItems=50, maxLength=256

Sample

REQUEST:
GET /dw/shop/v15_1/stores/(02108-21,03104-3) HTTP/1.1
Host: example.com
Accept: application/json

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=900,must-revalidate
Content-Length: 431
{
  "_v":"15.1",
  "count":2,
  "total":2,
  "data":
  [
    {
      "address1" : "333 Washington St",
      "city" : "Boston",
      "country_code" : "US",
      "email" : "[email protected]",
      "id" : "02108-21",
      "name" : "Downtown TV Shop",
      "phone" : "+1-617-695-1565",
      "postal_code" : "02108",
      "state_code" : "MA"
    },
    {
      "address1" : "239 Bridge St",
      "city" : "Manchester",
      "country_code" : "US",
      "id" : "03104-3",
      "name" : "Gardena Mart",
      "phone" : "+1-603-715-9773",
      "postal_code" : "03104",
      "state_code" : "NH"
    }
  ]
}

Get Store

To access a store, you construct a URL using the template shown below. This template requires you to specify a store id. In the response, the server returns a corresponding store document.

Url

GET http://hostname:port/dw/shop/v15_1/stores/{id}

Formats

json, xml

Authentication

Name Description
None No authentication.

Response Document

Store

Path Parameters

Parameter Type Description Constraints
id String The id of the requested store. maxLength=256

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 NotFoundException   Thrown if the requested store was not found

Sample

REQUEST:
GET /dw/shop/v15_1/stores/ma-bos-dt HTTP/1.1
Host: example.com
Accept: application/json

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=900,must-revalidate
x-dw-version-status: beta
Content-Length: 275

{
  "_v" : "15.1",
  "address1" : "333 Washington St",
  "city" : "Boston",
  "country_code" : "US",
  "email" : "[email protected]",
  "id" : "ma-bos-dt",
  "name" : "Downtown TV Shop",
  "phone" : "+1-617-695-1565",
  "postal_code" : "02108",
  "state_code" : "MA"
}