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.

Delivery request example

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.

Distances

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.

Time

Promoted supports time-to-now, time of day, time zone awareness, sine and cosine transformations, and more.

Timestamps

Timestamps should be sent to Promoted as epoch milliseconds.

Promoted will automatically represent this value as a time-from-now feature with the same name. For example, if the value of an entry in the Item CMS is created_at="2024-11-10", then the value of the feature created_at will be the number of milliseconds at the time of Delivery when logged and when used in machine learning inference or blender rules. If 25 hours later, then the feature value will be 25 _ 60 _ 60 _ 1000 = 90,000. If 43.2 hours later, then 43.2 _ 60 _ 60 _ 1000 = 155,520.

Promoted will still use the exact value of the timestamp as a feature as well. The numeric range is between 1999-12-31 16:00:00 as 946684800[_1000] and 2050-02-10 16:00:00 or 2528150400[_1000].

Time zone awareness

Our search and ads optimization considers the user's time zone. This is useful, for example, in ads pacing. Ads pacing compares the actual cumulative delivery (as a percentage of the target) to an expected cumulative delivery (as a percentage of the target) within 24 hours or a different fixed time period. Calculating an absolute time (e.g., UTC 00:00 to 23:59) may unequally compare ads delivery to different users, so Promoted uses the relative time on a user-by-user basis.

Sine and cosine transformations

The exact time values are more difficult for models to learn from and may have limited usefulness depending on their application. Time data (e.g., time-of-day or time-of-year) is inherently cyclical. Sine and cosine are standard transformations that preserve this cyclical nature (essentially, by mapping the data to a circle), enabling Promoted's models to learn from the data more effectively.

Privacy

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.