Maps and Geolocation

Overview of when geolocation data is useful and what features to send.

Use and Availability

Promoted uses geolocation data to optimize search and ads when it is made available. For clients whose listings correspond to a physical location (e.g., restaurants or hotels), it is common to use a hybrid user interface with a navigable map and an associated list of ranked insertions. The geolocation of these listings should be sent to Promoted along with their other properties.

While some marketplace listings like consumer products, jobs, or online courses may not have a precise associated location, Promoted’s model can still learn on geographical data, like the location of the user, if provided. For example, a user based in New York may be more historically likely to order a particular consumer product than a user in San Francisco.

Promoted has many features pre-built around map size, distance, bounding box relationships, and latitude and longitude; see below. This ensures that the models are well-informed about the map state to make the best optimizations for specific locations on the map.

Sending Data to Promoted

Types of data

Clients should send all geolocation data to Promoted through the same requests and CMS calls as other data. Data being sent to Promoted should always be as detailed as possible, especially for clients with a map UI or those that otherwise use physical location in the platform. Just like other data, Promoted’s advanced model will use the values as features, and the most accurate results come from the most accurate and available data.

The ideal features are latitude and longitude. This data is sent via JSON using a string representation, as JSON does not maintain precision on floating point numbers. Promoted extracts these numerical features from the strings.

Below is an example of a real client Delivery request, showing the structure of how geographical data may be sent to Promoted. Non-geographical values are removed and the remaining are obfuscated.

    "user_info": {},
    "timing": {},
    "client_info": {},
    "device": {},
    "use_case": "SEARCH",

    // Geographical filters are shown; other search filters are obfuscated
    "properties": {
        "struct": {
            "search": {
                "filter_1": 0,
                "filter_2": "",
                "filter_n": 0,
                "filter_bounding_box": {
                    "northeast_latitude": 0,
                    "northeast_longitude": 0,
                    "southwest_latitude": 0,
                    "southwest_longitude": 0
                "filter_ne_lat": 0,
                "filter_ne_lng": 0,
                "filter_sw_lat": 0,
                "filter_sw_lng": 0,
                "filter_country_code": "US",
                "search_scope": "geocenter"
            "last_location_search": {
                "q": "",
                "lat": 0,
                "lng": 0,
                "ts": "2024-01-01T23:59:00-04:00"
    "paging": {...},
    "client_request_id": "",
    "insertion": [
            "content_id": "",
            "retrieval_score": 0,
            "retrieval_rank": 0,
            "properties": {}

Relative distances

If sending latitude and longitude directly is not possible, Promoted uses any available proxies for distance to calculate the exact, approximate, or relative location. This may include other data from the viewport, like the viewport size and representations of the scale or zoom level. Although some metrics may not have precise geographical meaning, there is value in the relative positioning and proximity; in ranking, the relative order and scale of items are often more important than the exact measurements. Promoted calculates relative distance based on the closeness of available data, and optimizes on that value.

Promoted also handles the relative shift and revised endpoints from the original search to a new search. For example, suppose a customer is looking for a hotel on a booking platform, performs a search query for a particular town, and then manually adjusts the map in the viewport. In this situation, Promoted is able to see that adjustment in the viewport and optimize recommendations accordingly.


Promoted uses latitude and longitude to calculate the Haversine distance, a standard measurement of the distance between two points on a sphere. The standard formula is as follows:

Promoted calculates the distance based on the provided data and uses the distance as a feature in its models.


The live geographical location of the user's device is geolocation data that may constitute personally identifiable information (PII) and may require additional sensitivity measures, which Promoted fully supports. To limit exposure of potential PII, Promoted supports obfuscating any live PII, if used. Additionally, Promoted does not use IP addresses and does not associate location data with userIDs. See the privacy section of the documentation for more detail.