Introduction

The Store Locators API provides a list of participating locations where consumers can load funds, locate a product, or use their digital wallet to pay.

Users have the option to display the list of locations using the physical address or geographic coordinates.

Locating a Participating Store

• Post-Production URI: https://api.certification.blackhawknetwork.com/locator/v1/stores
• Production URI: https://api.blackhawknetwork.com/locator/v1/stores

HTTP Header

The parameters below must be included in the header of the request:

Your header may look similar to the following example:

Content-Type: application/json
mid: 60300112329
tenant_id: ZXF15KX4R6L9PK18NTL5B0KL70
trace_id: 2132r32r32

Query Parameters

To retrieve a list of store locations, the following parameters can be included in the query:

See Store Locators Response Object for an example request.

URI: https://api.blackhawknetwork.com/locator/v1/stores?campaign=A8KVZCMG9Y49DB77B5HH3HTL7H&lat=37.7706&lng=-122.2648&page=0&pageSize=10&txn=Activation&product=987654321,987654322,987654323&radius=5000mi&trace_id=2132r32r32

Response

Store Locators Response Object

The Store Locators API will return a response containing an HTTP status code in the header and a JSON object in the body. This response will tell us if the inquiry was successful and display the location information for participating stores.

GET https://api.blackhawknetwork.com/locator/v1/stores?campaign=A8KVZCMG9Y49DB77B5HH3HTL7H&lat=37.7706&lng=-122.2648&page=0&pageSize=10&txn=Activation&product=987654321,987654322,987654323&radius=5000mi&trace_id=2132r32r32 HTTP/1.1
Accept-Encoding: gzip,deflate
Connection: Keep-Alive

{
    "locations": [
        {
            "siteId": "LZTP3MSCSGGRZP8C9NQ2SMXN3R",
            "siteName": "Trimmer SPA Store",
            "contactName": "STORE MANAGER",
            "addressLine1": "3382 Murphy Canyon Rd",
            "city": "San Diego",
            "state": "CA",
            "zipCode": "92123-2654",
            "country": "USA",
            "latitude": 32.8084,
            "longitude": -117.1349,
            "formattedAddress": "3382 Murphy Canyon Rd;San Diego, CA 92123-2654",
            "sort": 448.4423753762137,
            "phoneNumbers": [
                {
                    "number": "8746354733",
                    "type": "WORK"
                }
            ],
            "productId": "987654321"
        }
    ],
    "size": 10,
    "totalPages": 1,
    "totalElements": 1,
    "numberOfElements": 1,
    "number": 0,
    "first": true,
    "last": true
}

Phone Numbers object

HTTP Status Codes

HTTP response codes are used to indicate the outcome of the request.

The following table shows the HTTP codes and their meanings.