Abstract

The "Get Store Location" endpoint (POST /v2/ads/getstorelocations) provides a mechanism for partners to retrieve nearby store locations associated with specific advertisement IDs, based on a customer's location. This is intended to enhance the user experience by allowing customers to find relevant store locations for advertised offers they are viewing, directly within the application or widget.

Overview

Purpose

When a customer interacts with a widget displaying partner ads — selected and ranked based on their transaction history — a need may arise to locate nearby physical stores relevant to a specific ad. This endpoint enables partners to fetch a list of store locations for one or more ad IDs in the context of the customer's current location.

How It Works

Trigger: When a customer requests to view store locations for a specific ad, the endpoint is called.
Inputs: The request requires:
- A list of adIds (advertisement identifiers).
- The customer's location, provided either as latitude/longitude or postal code (latitude/longitude takes precedence).
- A radius (in meters) specifying the maximum search distance (up to 48,000 meters / ~30 miles).
Outputs: The response returns a mapping of each ad ID to a list of nearby store locations, including details such as store name, address, phone number, distance, and geographic coordinates.

Endpoint

POST /v2/ads/getstorelocations

Request

Key	Type	Required	Description
`adIds`	string []	Yes	Fetch StoreLocations Nearby provided customer location.
`customerLocation`	CustomerLocation	Yes	Provide Customer location Either Lat/Long OR postalCode when getAds is requested to fetch Store Locations Near a customer location. If both are provided, the postal code will be ignored.
`storeLocationRadiusInMeters`	int	Yes	Max radius for which merchant locations will be returned.This should be expressed in meters Max value = 48000m (approximately 30 miles)

Response

Key	Type	Description
adStoreLocations	Map <string, storeLocations []>	AdId - list of Store locations metadata pairing

Example

Sample Request:

{
    "adIds": ["44644474332", "65675755751"],
    "customerLocation": {
        "latlong": {
            "latitude": 33.84846115112305,
            "longitude": -79.06450653076172
        }
    },
    "storeLocationRadiusInMeters": 1000
}

Sample Response:

{
    "adStoreLocations": {
        "44644474332": [
            {
                "storeName": "Mcdonalds",
                "address": { ... },
                "phoneNumber": "123-456-7890",
                "distance": 1000,
                "latitude": 37.7749,
                "longitude": 122.4194
            }
        ],
        "65675755751": [
            {
                "storeName": "Dunkin",
                "address": { ... },
                "phoneNumber": "123-456-7291",
                "distance": 346,
                "latitude": 15.7749,
                "longitude": 102.4194
            }
        ]
    }
}

Use Cases

Customers can quickly find physical store locations for offers shown in ads.
Partners can enhance the utility of ads by linking them to actionable, location-based store information.
Useful for mobile apps, web widgets, or any interface where location-aware advertising is beneficial.

Summary

The Get Store Location endpoint is designed to bridge digital ads and real-world store locations, enabling seamless, location-based experiences for customers and partners.