Location

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).
  • 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

KeyTypeRequiredDescription
adIdsstring []YesFetch StoreLocations Nearby provided customer location.
customerLocationCustomerLocationYesProvide 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.
storeLocationRadiusInMetersintYesMax radius for which merchant locations will be returned.This should be expressed in meters Max value = 48000m (approximately 30 miles)

Response

KeyTypeDescription
adStoreLocationsMap <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.