Bid Enrichment

The MediaMath platform enables marketers to target campaign delivery with data provided by partners in real-time. Integrations that provide real-time targeting data are considered bid enrichments.

Use cases for bid enrichment include:

• Brand safety, including IVT avoidance and alignment with Global Alliance for Responsible Media
• Viewability, so you can target inventory based on how viewable a given impression is likely to be
• Geography, so you can target campaign delivery based on location dimensions
• Content categories, including IAB content categories, and custom keyword lists, to reach people while they consume content relevant to your product or service
• and many others, including environment, weather, and language targeting.

Contact us to learn more about a bid enrichment partnership.

The MediaMath partnerships team will establish a data vendor account and, in some cases, determine the structure of a commercial agreement (i.e. for 3rd party data providers). Prior to reaching out to the partnerships team, familiarize yourself with the MediaMath Privacy Policy to understand how bid stream data can be used.

Integration Questions

Typically, we'll ask the following questions during a technical kick-off call with prospective bid enrichement partners:

• Does your API service have a global presence?
• Does your API service have a QPS cap? If so, what are the caps, and are they global and/or regional?
• Does your API service back-pressure during high load? If so, what is the HTTP response code during back-pressure?
• How do we tell if enrichment data are not available yet on your end? What is the cache-control value for that situation?

Bid Enrichment Request Flow

When the MediaMath bidding platform receives a bid request, it extracts elements of the request needed by the bid enrichment partner and then makes a request to the partner’s enrichment API with those data elements. The request to the partner can be an HTTP GET or HTTP POST request.

The partner’s API will respond with an array of segment codes for MediaMath to consider for the bid request. If the response takes longer than 15 ms, MediaMath will resume the bidding process without the partner’s data. When the response is received from a partner, it will be cached for use on subsequent bid requests based on the Cache-Control header in the response (see example response below). The cache is co-located with the MediaMath bidding services to ensure that real-time enrichment happens as quickly as possible. Pushing data to MediaMath cache outside of this request flow is not supported.

Example Bid Request Elements

MediaMath will provide bid enrichment partners with elements of the bid request required to evaluate the media opportunity and return segment codes for MediaMath to consider for the bid request. For reference on what elements of the bid request partners may request, review the OpenRTB protocol.

Example bid request elements include:

Standard Enrichment API Specification

Typically, bid enrichment data providers have an API that MediaMath integrates with; however, we have a standard enrichment specification that data providers can reference.

API Protocol

• HTTP protocol: HTTP/1.x
• Supported method: GET, POST
• Security protocol: SSLv23 (SSLv3 or TLSv1)
• Supported authentication: BASIC

HTTP Caching

A standard HTTP caching mechanism allows enrichment data providers to influence how the MediaMath system caches data, i.e. segment codes.

• Cache-Control: max-age=<num-of-seconds> -- instruct MediaMath how long we can cache the data
• Cache-Control: no-cache -- instruct MediaMath not to cache the data
• Age: <num-of-seconds> -- indicates the response was from a cache at origin and how much time the data have been in the origin's cache. When both "max-age" and "age" values present in a query response, they instruct MediaMath to cache the data no more than (max-age - age) seconds.

Because of the high volume of bid requests MediaMath processes, it is not recommended to use small max-age value (e.g., less than 10s) in cache-control header, even for (5xx) error responses.

Example Request Format

 Method: GET
 URL:    http[s]://domain[:port]/path?param1=v1[&param2=v2...]

Schema for Standard Response

Although MediaMath typically integrates with bid enrichment partner API specs, support for our specification is recommended. The following outlines our standard JSON response.

{
    "doc": "Schema for MediaMath Standard Enrichment API Specification",

    "type": "record",
    "fields": [
        {
            "name": "result_code",
            "type": "int",
            "doc":  "code signify the query result. 1 = success; 0 = failure"
        },
        {
            "name": "result",
            "type": ["null", "array"],
            "default": null,
            "doc":  "standard enrichment data, in the form of array",
            "items": {
                "type": "record",
                "fields": [
                    {
                        "name": "dim_id", 
                        "type": "int",
                        "doc":  "dimension-ID, will be provided by Mediamath"
                    },
                    {
                        "name": "values", 
                        "type": "array",
                        "items": "long",
                        "doc":   "enrichment data in form of list of numeric partner segment codes"
                    }
                ]
            }
        },
        {
            "name": "kvps",
            "type": ["null", "array"],
            "default": null,
            "doc":  "enrichment data in form of key-value pairs",
            "items": {
                "type": "record",
                "fields": [
                    {
                        "name": "dim_id", 
                        "type": "int",
                        "doc":  "dimension-ID, will be provided by MediaMath"
                    },
                    {
                        "name": "values", 
                        "type": "array",
                        "items": "record",
                        "fields": [
                            {
                                "name": "key",
                                "type": "string",
                                "doc":  "key is the segment code, value is an attribute for the segment code, like a score value of the segment"
                            }
                        ]                        
                    }
                ]
            }
        }
    ]
		}

Description of Response

Description of Object: Result

Description of Object: KVPS

Note: As the use of attributes of segments (like a score or confidence level) is specific to a partner, it is not recommended to use the "kvps" object to pass segment codes to MediaMath.

Example Response

HTTP/1.1 200 OK 
Content-Length: 380 
Content-Type: application/json 
Cache-Control: max-age=21600s

{
   "result_code": 1,
   "result": [{
      "dim_id": 3,
      "values" : [ "961", "965", "967", "968", "1255", "1256", "1257", "1295", "1524" ]
   },
   {
      "dim_id": 7,
      "values": ["4512", "4513", "4514", "4515", "4581", "4587", "4597", "43482", "43518", "71021", "71029", "71045", "71053", "71061", "71077"]
   }]
}

result_code indicates 1 for success

result an array of result objects

result.dim_id a required internal MediaMath code; 3 is used as an example

result.values an array of data provider segment codes