How does our tag work? (Traffic API)

The system that serves our dynamic ads onto the internet is called Traffic. This article explains how to interact with it.

Ad requests

The main way to request a dynamic ad from Traffic is via a GET request to the ads.amillionads.com endpoint. This URL takes a set of input parameters and returns a response in the specified format.

Example:

https://ads-us.amillionads.com/go/414OCx7?source=ttd&data.pmpid=1234

Our server clusters are in the US and EU and can be explicitly addressed with the ads-us or ads-eu subdomains. All requests must be https.

Path parameters

Pub key

string Required 🔴

The publication id of the script in the A Million Ads system. This is provided when the script is published within Studio on the Publish page.

Example: 414OCx7

Query string parameters

source

string

Default: No default, this is provided in the tag when published.

Specifies the parser to use to interpret the request. If no parser is specified, the parser listed in the script is used. The parser is config that sets up the correct parameters for each publisher/DSP/ combination. We set these up in advance for each integration that we certify.

output

string

Default: empty / blank / not present.

Specify the output format of the response. Options:

empty will respond in the output format specified by the parser.
source is the custom output template that is specified within the parser, so that publishers can get their own format of output (most often VAST XML). This is provided when the script is published. This is the default if no output parameter is specified. Example
short returns a short output just listing the file location and any companion image or link in JSON. Example
preview is used by the Admin interface to quickly preview audio edits. Using preview reloads the script and parser from Admin API, updating the cache for the script and parser. Example
vast returns an XML document in the IAB VAST specification format. This is the standard for ad tech and the most common format of response. Example
file returns a 301 redirect to the location of the audio file itself with the stream set to play the file (useful for links in emails/Slack to play one version). Example
ok returns a 200 OK status code. Example

Other formats and types are available depending on what is required by the request.

Example:

output=short

data.<field>

string

Data can be passed to Traffic from a source system, encoded according to the parser specified in source. The data in the payload is arranged as key:value pairs with a prefix of “data.” and should be URL Encoded. Any number of data pairs can be appended, separated by an & symbol. Data can also be injected via a URL Encoded JSON object with the parameter name “data”.

Examples:

data.genre=pop
data.o45=true
data.pmpid=3f52g3
data.dma=501

default=true

Boolean optional

If the parameter default is passed with the value true then the default version of the ad will be returned, i.e. the version of the ad where all data used in the processing is unavailable. This can be used to provide a backup version of the ad. Note: rules like random and link will still be active as their data is always available.

HTTP Header parameters

User-Agent

string Required 🔴

The user agent string normally passed from the client device in each request. Required in order to inform device type and OS creative rules.

Example:

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/52.0.2743.116 Safari/537.36

X-Forwarded-For

string Required if request is being proxied and IP header is server address 🔶

The IPv4 or IPv6 address of the client device making the request (if being proxied). If not present the value of the IP header will be used. We require the client IP for our time/date and location creative rules.

Examples:

81.25.255.144
2604:3d09:6a84:3300:94ad:93d4:502b:273

Errors

Pub code doesn't exist or not published: 404

Error in script: 502

Error in parameters: 503