outletQuery.html - alexistaylor-cocacola/Seller-API-Documentation Wiki


Home > Delivery Date APIs > Outlet Query


Outlet Query API details for sellers

This is an API used to get a list of outlets. This API will receive a state, state and city, or postal code, as well as the desired format for the data(json or csv). It will return a callback code which can be used with this same API to poll for results. Once the request is finished processing, the callback code can be used to get a URL link to a list of information on outlets available in that area.

This page describes how sellers may utilize the outlet query API to receive a list of outlet information from Wabi2b.


Request (Original Request)

Sandbox: https://sandbox.sellerapi.mywabi2b.com/v1/listOutlets
Production: https://sellerapi.mywabi2b.com/v1/listOutlets

All calls to this API are throttled at max 750 calls per 5 minutes and max 15,000 calls in 24 hours per seller.

The get request can be used by passing a state, city, and/or postal code, as well as a format, on URL parameters. It will respond with a callback code that you can then use to get status information and if it is finished a URL that you may use to download your list of outlet information.

To use this API you must first make a GET call with querying parameters such as state OR state and city OR postal code. You will then receive a callback code. Once you have this callback code, in order to receive your results, you must send another GET request where callBackCode is the ONLY parameter, containing the callback code from your first call. Once your request is done processing this is how you will receive your results. An example is given further down in this article.

You must send an Authorization header containing a JWT token which will be used for authentication purposes. You will obtain this JWT token from the Authenticate API. For more details, see the authentication page.
The name of the Authorization header must be Authorization.

You must also provide an x-api-key on a header which will be given to you during onboarding.

Request Parameters

Param Name Description
state The 2-character state code you want to receive outlet information for.
city The city you want to receive outlet information for.
postalCode The postal code you want to receive outlet information for.
format The desired format to receive outlet information in. Possible values: "json", "csv"

Note that you can send any combination of state code, city, and/or postal code. If you do not send a valid combination you will simply not get any results. PLEASE NOTE that this extends to typos- if you misspell a city or give a state's full name rather than its 2-character code, you will not get results.

Example GET Request Calls:

Headers:
Authorization: jwtTokenHere
x-api-key: keyGoesHere

https://sandbox.sellerapi.mywabi2b.com/v1/listOutlets?state=CA&format=json
https://sandbox.sellerapi.mywabi2b.com/v1/listOutlets?state=CA&city=San Diego&format=json
https://sandbox.sellerapi.mywabi2b.com/v1/listOutlets?postalCode=92101&format=csv

Response (Original Request)

Field Name Data Type Description
callBackCode string The callback code you may use to poll for results. Send as the only parameter on a GET request for the results.

JSON schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "$title": "Outlet Query Original Get Response Payload",
    "description": "The payload for a Outlet Query original get response",
    "type": "object",
    "required": [],
    
    "properties": {
        "callBackCode": {
            "description": "A callback code to use in a GET call to poll for results",
            "type": "string"
        }
    }
}

Example Response Payload:

{
    "callBackCode": "5d4ea3532d50c4473164250c4058e7d04a90ec7e"
}

Request (Callback)

Sandbox: https://sandbox.sellerapi.mywabi2b.com/v1/listOutlets
Production: https://sellerapi.mywabi2b.com/v1/listOutlets

To use this part of the API you must first make a GET call with querying parameters such as state OR state and city OR postal code. You will then receive a callback code. Once you have this callback code, in order to receive your results, you must send another GET request where callBackCode is the ONLY parameter, containing the callback code from your first call. Once your request is done processing this is how you will receive your results. This section details how to make the second call using the callback code.

You must send an Authorization header containing a JWT token which will be used for authentication purposes. You will obtain this JWT token from the Authenticate API. For more details, see the authentication page.
The name of the Authorization header must be Authorization.

You must also provide an x-api-key on a header which will be given to you during onboarding.

Request Parameters

Param Name Description
callBackCode Exclude this parameter on your first call, then exclude all other parameters and pass the callback code you received from your first call to receive results.

Example GET Request Calls:

Headers:
Authorization: jwtTokenHere
x-api-key: keyGoesHere

https://sandbox.sellerapi.mywabi2b.com/v1/listOutlets?callBackCode=5d4ea3532d50c4473164250c4058e7d04a90ec7e

Response (Callback)

Response Payload Fields

Field Name Data Type Description
filePath string The URL path that can be used to download the results
status string The status of the process

JSON schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "$title": "Outlet Query Callback GET Response Payload",
    "description": "The payload for a Outlet Query callback get response",
    "type": "object",
    "required": ["status"],
    
    "properties": {
        "filePath": {
            "description": "The URL path that can be used to download the results",
            "type": "string"
        },
        "status": {
            "description": "The status of the process",
            "type": "string"
        }
    }
}

Example In Progress Response Payload:

{
    "status": "In Progress"
}

Example Completed Response Payload:

{
    "filePath": "https://sandbox.sellerapi.mywabi2b.com/tmp/outletQuery/result/2022-8/1/18/5d4ea3532d50c4473164250c4058e7d04a90ec7e.json",
    "status": "Completed"
}

Final Results from URL

This section describes the structure and examples of the final results that can be received from the URL given after the request is finished processing.

Response Payload Fields

Field Name Data Type Description
outletList array The list of outlet information.
outletList.outletNumber string The identifying outlet number for the outlet.
outletList.outletName string The name of the outlet.
outletList.outletStreetAddress string The street address of the outlet.
outletList.outletCity string The city of the outlet.
outletList.outletState string The state of the outlet.
outletList.outletPostalCode string The postal code of the outlet.

JSON schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "$title": "Outlet Query Result URL Payload",
    "description": "The payload for an Outlet Query Result URL",
    "type": "array",

    "items": {
        "type": "object",
        "required": ["outletNumber", "outletName", "outletAddress", "outletCity", "outletState", "outletCountry", "outletPostalCode"],

        "properties": {
            "outletNumber": {
                "description": "The identifying outlet number for the outlet.",
                "type": "string"
            },
            "outletName": {
                "description": "The name of the outlet.",
                "type": "string"
            },
            "outletAddress": {
                "description": "The street address of the outlet.",
                "type": "string"
            },
            "outletCity": {
                "description": "The city of the outlet.",
                "type": "string"
            },
            "outletState": {
                "description": "The state of the outlet.",
                "type": "string"
            },
            "outletCountry": {
                "description": "The country of the outlet.",
                "type": "string"
            },
            "outletPostalCode": {
                "description": "The postal code of the outlet.",
                "type": "string"
            }
        }
    }
}

Example JSON Response Payload:

[
    {
        "outletCity": "Test City",
        "outletCountry": "USA",
        "outletName": "Test",
        "outletAddress": "1 Test Street",
        "outletState": "CA",
        "outletPostalCode": "12345",
        "outletNumber": null
    },
    {
        "outletCity": "Atlanta",
        "outletCountry": "USA",
        "outletName": "Coca-Cola",
        "outletAddress": "1 Coca-Cola Plaza",
        "outletState": "GA",
        "outletPostalCode": "30313",
        "outletNumber": null
    }
]

Example CSV Response Payload:

outletName,outletAddress,outletCity,outletCountry,outletPostalCode,outletState
Test,1 Test Street,Test City,USA,12345,CA
Coca-Cola,1 Coca-Cola Plaza,Atlanta,USA,30313,GA