Use this endpoint to retrieve store locations for one or more specific offers
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).
- A list of
- 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.