ADmantX API Guide

Overview

Integral Ad Science's (IAS) ADmantX Platform is a real-time RESTful web service that performs semantic analysis of text via an HTTP/S request and provides a semantic descriptor as the response. The ADmantX Platform supports both GET and POST requests. The request (see section ADmantX Platform Service Request) must include the source to be analyzed in one of three forms:

1. The URL of a web page containing the text.

2. The text directly.

3. The HTML directly.

The ADmantX Platform Web Service provides the results of the semantic analysis from our pre-defined Contextual Taxonomy. The ADmantX Platform Taxonomy for Release 3.1 is a superset to the IAB Tech Lab Content Taxonomy V2.0. The ADmantX Platform Taxonomy provides additional levels of categories due to the details available from the semantic engine. Also included in our Taxonomy are names of the feelings, motivations, behaviors, and sentiment that can be evoked in the reader by the content. Please contact your IAS representative for a copy of the Taxonomy.

For the remainder of this specification the term "content" is used to represent the input to be analyzed by the service. Requests to analyze content will be comprised of key/value pairs defining the mode of the service environment and the format of the response. See section API Input Description for a description of all service request API input key/value pairs. The response format is described in section ADmantX Platform Service Response.

The ADmantX Platform supports the analysis of content in the languages identified in the following table:

Notes:

1. Each language in the table identifies their corresponding ISO 639-1 language codes.

2. Each ADmantX Platform Service instance minimally supports requests for English and Italian content. Additional languages that can be supported from the table above may not be available in the service you are authorized to use. Contact your IAS representative to discuss your language requirements.

3. The support for Chinese includes Simplified Chinese and Traditional Chinese.

ADmantX Platform Service Request

The ADmantX Platform Service is a RESTful web service that accepts requests via HTTP or HTTPS, and using the methods GET or POST. The ADmantX Platform Service processes requests that contain the "request" parameter as a JSON object containing a list of key/value pairs defining the target content to be analyzed with a variety of options for how the response should be formatted. The ADmantX Platform Service ignores the HTTP headers "Content-Type" and "Accept" since it expects the input to be in plain text and encoded in the UTF-8 character set.

Response Headers

The ADmantX Platform Service HTTP response will include the headers "Content-Type," "Content-Length," "Connection," and "Access-Control-Allow-Origin" with the following values as shown below:

The ADmantX Platform Service supports HTTP 1.0 and HTTP 1.1. It is highly recommended to use HTTP 1.1 which defaults to using persistent connections (noted in the "Connection: keep-alive" header above). Persistent connections to the ADmantX Platform Service optimizes performance by reducing the overhead of closing connections after a response is sent and then reopening new connections. When using the HTTP GET method, append the "request" parameter to the service URI as a query parameter. When using the POST method, store the "request" parameter in the HTTP request body.

ADmantX Platform Web Service Request Format

The format of the service URI for a GET request to the ADmantX Platform Service is as follows as shown below:

The <HOST> identifies the server where the ADmantX Platform Service instance is located. The parameter "request" is JSON, which includes the keys and their values that are verified by the ADmantX Platform Service, and used to perform the analysis and format the response. The JSON keys' values supplied will replace the tags in the above example delimited by "<" and ">" characters. The required and optional key/value pairs are described in section API Input Description.

ADmantX Platform Web Service Example Request

The following is an example of the URI for a GET request to the ADmantX Platform Service with a number of required and optional key/value pairs:

Note: All of the JSON keys supplied in a request must be in lowercase as depicted in this specification. Failure to do so will result in an error response. If a value of a key is treated in a case-sensitive manner it is described as such below, otherwise the value can be supplied in any case.

API Input Description

This section contains a detailed description of the ADmantX Platform Service API's input JSON key/value pairs. All key/value pairs are described below. Those key/value pairs not listed as "optional" are required.

The following list contains a list of the API input keys and a description of their values:

• "key": (string) The unique API key provided to the customer providing access to the ADmantX Platform Service.

• "type": (string) The type of document to be analyzed. It defines the type of data provided as the value for the "body" key. In order to use a value for this field, it must be enabled for your API key. The values enabled for this field are based on the service contract established with ADmantX. Allowed values and their definitions are:

  • "txt": The "body" key's value is in plain text.

  • "url": The "body" key's value is a URL for a web page.

  • "html": The "body" key's value is the HTML content of a web page.

• "method": (string) The method required for the analysis of the document. Allowed values and their definitions are:

  • "descriptor": This value is the only method currently enabled. It means the ADmantX Platform will return a semantic descriptor of the analyzed content.

• "mode": (string) Identifies the operating mode of the ADmantX Platform Service environment. Allowed values and their definitions are:

  • "sync": This value means the request is intended for a Synchronous Mode environment of the ADmantX Platform Service.

  • "async": This value means the request is intended for an Asynchronous Mode environment of the ADmantX Platform Service.

Requests to a Synchronous Mode ADmantX Platform Service must have the mode value set to "sync". Responses from a synchronous ADmantX Platform Service are sent only when the results of the analysis are available, or an error occurs while processing the request. Synchronous Mode environments contain several timeouts that can be triggered during request processing. Service timeouts are designed to avoid abnormally long request processing times. Timeouts results in an error response returned to the requesting client. Error responses contain an "info" field describing the cause. See section Error Messages for a description of the errors provided in the "info" field.

Requests to an Asynchronous Mode ADmantX Platform Service must have the mode value set to "async" and the type value set to "url". Responses from an asynchronous ADmantX Platform Service are sent immediately with either the result of the page's analysis (from an internal cache) or a response indicating the page's content is being analyzed (also known as the "other" response). If there are no cached results for the requested URL, the URL is stored for processing, and the "other" response is provided in the output parameter field "descriptor" (see section Example of the "other" Response for an example of the "other" response). The "other" response will be returned for the page until the analysis results are available in the cache.

Note: If the value of the mode key is "async" and the value of the type key is "txt" or "html" the response will contain an error.

• "body": (string) This key defines the source of the content to be analyzed. Allowed values and their definitions are:

  • If the type key is "txt" then this value is the source text to be analyzed.

  • If the type key is "url" then this value is the source URL of the content to be analyzed.

  • If the type key is "html" then this value is the HTML to be analyzed.

  Note: This value must be URL encoded.

• "decorator": (string) - (optional) This key defines a response format. The value provided must be in lower case. See section ADmantX Platform Service Response Examples for examples of response formats affected by this key. Allowed values and their definitions are:

  • "default": This decorator provides the names of the "categories", "feelings", "entities", and "admants" (custom segments) for the analyzed content in a line separated list. The following is an example of the "default" decorator response.

• "json": This decorator provides the response in JSON. This "decorator" is implied so the request can exclude the "decorator" key if JSON is the desired response format. See section Example of the "json" Decorator Response for examples of JSON responses.

• "javascript.<decorator>": This decorator provides the response as JavaScript code that will be executed by the browser when returned. The tag "<decorator>" is replaced with the name of the file containing the template used by ADmantX Platform to produce the JavaScript code for the response. The JavaScript decorator template file is created collaboratively between the customer and the ADmantX technical team. Generally this decorator is used to provide the names of the categories, feelings, entities, and admants in one or more JavaScript variables. The returned variables are parsed in customer-written JavaScript code deployed on the web page to perform the required processing of the values of those variables.

• "template.<decorator>": This decorator allows the customization of the response to be any form of data as required by the customer. You will collaborate with the ADmantX technical team to decide on the format of the response and the template will be set up accordingly. The tag "<decorator>" is replaced with the name of the file containing the template used by the ADmantX Platform Service to produce the custom response.

For most website publisher integrations where real-time contextual ad targeting is offered, this decorator is configured to provide the response as JSONP (JSON with padding), which will be a call to a JavaScript function (written by the customer team) wrapping the JSON response as the arguments (the ADmantX semantic analysis result) that will be processed by the function. The JavaScript function called will then send the parsed key/value pairs to an external system. For contextual targeting and/or brand safety the results are sent to an Ad Server to deliver the proper ad(s) or block ads by certain advertisers based on the established campaigns.

Example of a JavaScript Decorator Response

The following is an example of the "javascript.<decorator>" decorator response showing two variables set to the semantic analysis results with separators:

Example of JSONP Response via Template Decorator

The following is an example of the "template.<decorator>" decorator response showing the function "admantx_callback" called with the JSON payload:

Key "decorator" notes:

1. Template customization is part of the setup of integration with the ADmantX Platform Service and may incur a fee. Contact your IAS representative if you require output template.

2. If the key is misspelled in the request it is ignored and the implied JSON response is returned.

• "filter": (array of strings) - (optional) This key is used to select the key/value pairs that will be provided in the "json" decorator response (see section ADmantX Platform Service Response for details of each key/value output). Some key/value pairs are independent from the filter and are always provided in the response. See section Service Response Formats for a description of all the output key/value pairs provided in the "json" decorator response. If the key "filter" is missing or is empty, the "default" filter is automatically selected. In order to use a value in this field, it must be enabled for your API key. The values enabled for this field are based on the service contract established with ADmantX. Allowed values and their definitions are:

  • "default": Provides the key/value pairs "categories", "feelings", "entities", and "admants" in the response.

  • "text": Provides the key/value pairs "body", "body_length", "title", "description", and "keywords" in the response.

  • "categories": Provides the key/value pair "categories" in the response.

  • "feelings": Provides the key/value pair "feelings" in the response.

  • "sentiment": If the "default” and "feelings" filters are not enabled and this filter is enabled for an API key, then including this filter in the request provides only the sentiment categories in the "feelings” response field, excluding all other emotions categories. This value is available in API Release 3.1.8 and higher.

  • "entities": Provides the key/value pair "entities" in the response.

  • "relations": Provides the key/value pair "relations" in the response.

  • "admants": Provides the key/value pair "admants" in the response.

  • "geo": Provides the "geographical position of the places” retrieved in the documents (e.g. in which region, in which country, in which continent they are located).

  • "domains": Provides the key/value pairs "domain_categories" and "domains_info".

Note: Domain categorization is only available in select ADmantX Platform Service instances. It also requires authorization and can incur an additional fee. For new clients, reach out to your IAS Solution Engineering representative to enable domain categorization. For existing clients, reach out to your dedicated Technical Client Services representative.

Invalid Filter Parameter Error Response

If you use this filter and are not authorized a "KO" response is returned with the info field as follows:

Key "filter" notes:

1. The results of the filter "geo" are visible only if the key "entities" is present.

2. If this key is misspelled it is ignored and the default filter is selected.

3. The "domain_categories" key/value pair contains the result of the categorization of the domain of the URL received. The domain taxonomy is different than the page-level taxonomy provided in the standard data result. This key must be enabled by ADmantX for the API key making the request. When enabled, this key will only work for requests with the input key "type" set to "url".

• "lang": (string) - (optional) This key/value pair is used to define (force) the language of the document to be analyzed. If this parameter is empty, the ADmantX Platform Service will automatically detect the language of the content being analyzed. To analyze documents containing shorter text, it is recommended that this parameter be set to the language of such documents due to the fact that language recognition could be inaccurate. Please contact your IAS representative for assistance in the language setting if needed for your integration.

• "reprocess": (boolean) - (optional) This key is applicable only to asynchronous ADmantX Platform Service environments. Allowed values and their definitions are:

  • "false": The response will contain the currently cached semantic descriptor for the web page. This value is the default if the parameter is not included in the request.

  • "true": Reprocessing of the web page is forced. If there is a semantic descriptor cached for the web page, it will be replaced. This value will cause the "other" response to be returned indicating the web page is in the process of being analyzed.

• "tag": (string) - (optional) This key is used to set a tag in the response descriptor (see the description of the corresponding output key "tag" below for details).

• "custom1" through "custom10": (string) – (optional) These keys are used to set custom fields in the response descriptor (see the description of the corresponding output key "custom1" through "custom10" below for the details). The maximum number of custom fields allowed is ten. To include one or more of these keys the numeric order from 1 to 10 must be maintained. That is if there will be three custom keys they must be "custom1", "custom2", and "custom3". Any gaps in the numeric order will cause those after the first gap to be ignored and not returned in the response.

• "meta": (array of strings) - (optional) This key is used to select which content must be analyzed from the requested URL or HTML. By default (when this key is missing from the request) the ADmantX Platform Service analyzes the text of the page (the main article) along with the values (text) of the HTML <meta> tags "title", "description" and "keywords". This parameter is used to identify which of these <meta> tags to include or exclude in the analysis. This parameter will be ignored if the "type" key is set to "txt". Include one or more of the valid values below to include those <meta> tag values in the analysis. To exclude any of the <meta> tags from analysis include the properties desired in this array and omit the ones not desired. If the array is empty the default is to use all four of these <meta> tag values in the analysis. Allowed values and their definitions are:

  • "body": If this value is present in the array the main article text contained in the page will be analyzed.

  • "title": If this value is present in the array the <meta> tag "title" text will be analyzed (if present in the HTML).

  • "description": If this value is present in the array the <meta> tag "description" text will be analyzed (if present in the HTML).

  • "keywords": If this value is present in the array the <meta> tag "keywords" text will be analyzed (if present in the HTML).

ADmantX Platform Service Response

This section describes the format of the response to a request to an ADmantX Platform Service.

Service Response Formats

The default output data format in the response is a JSON descriptor that contains the semantic results of the analysis in key/value pairs providing the context as category names from the ADmantX Taxonomy with additional information. Below is a detailed description of all the key/value pairs provided in the response. This response format is automatically provided when the request parameter "decorator" is missing from the request or is in the request with the value "json".

Fixed Output Keys: The following key/value pairs are always included in the "json" response descriptor regardless of the filter used.

• "docID": (string) An ID code assigned to the document.

• "key": (string) The unique API key provided to the customer by ADmantX and retrieved from the request.

• "version": (string) The version of the ADmantX Platform deployed in the service environment.

• "fetchingDelay": (long) The time spent downloading the web page (in milliseconds).

• "delay": (long) The time spent analyzing the document (in milliseconds).

• "converter": (string) The converter used to extract the plain text from the web page.

• "info": (string) This key contains the value "OK" if the document was analyzed without errors, otherwise this key contains the type of error that occurred (see section Error Messages for the list of possible errors).

• "valid": (string) This key indicates whether the analysis was performed successfully ("OK") or whether an error occurred ("KO").

• "timestamp": (long) The POSIX timestamp in milliseconds of the time when the analysis started.

• "nwords": (int) The number of words contained in the analyzed document.

• "url": (string) The URL provided in the request.

• "tag": (string) This key contains the same value as the request key "tag". It is excluded from the response if there was no request key "tag" or if its value was an empty string.

• "custom1" through "custom10": (string) These keys contain the same value as the request keys "custom1" through "custom10". The output key "custom1" contains the value of the request key "custom1", and the output key "customX" contains the value of the request key "customX". These properties are used to attach a certain value to the response, usually cookie identifiers.

• "body[en]": (string) This key contains the English translation of the analyzed content whose source language is different from English or Italian.

• "title[en]": (string) This key contains the English translation of the <meta> tag "title" value from the requested URL or HTML whose source language is different from English or Italian.

• "translator": (string) This key contains the name of the automated machine translator used for translating documents from any of the supported languages into English. Italian is not translated as it is natively analyzed by the ADmantX Platform Service semantic analysis engine.

• "descriptor": (string) This key is included only if the request key "mode" is set to "async" and when the analysis results of the page are not in cache. The value returned is always set to "other" to indicate that the analysis of the requested URL is being processed by the ADmantX Platform Service. Once the results are available, they are stored in cache for subsequent requests for up to 24 hours.

• "lang": (string) The ISO 639-1 language code (two-character code) identifying the detected language of the text analyzed. If the request key "lang" was provided, then this key's value is set to it.

The following keys are included in the JSON response depending on the filter set in the request (see "filter" in section API Input Description for more information). The following list describes the output keys provided based on the value of the request key "filter":

• "description": (string) This key contains the value of the <meta> tag "description" if present in the HTML analyzed by the system.

  Filter: text

• "keywords": (string) This key contains the value of the <meta> tag "keywords" if present in the HTML analyzed by the system.

  Filter: text

• "title": (string) This key contains the value of the <title> tag in the HTML analyzed by the system.

  Filter: text

• "image": (string) This key contains the link to the most relevant image included in the web page.

  Filter: text

  Filter: image

• "body": (string) This key contains the text analyzed by the service. The text provided is either extracted from the web page or provided in the request key "body" when the request key "type" is set to "txt" or "html".

  Filter: text

• "body_length": (int) This key contains the number of characters of the text analyzed by the system.

  Filter: text

• "categories": (array of JSON objects) This key contains the list of contextual categories determined from the semantic analysis of the content.

  Filter: default or categories

Each "categories" array element returned contains:

"name": (string) This key contains the name of the category from the ADmantX Taxonomy.

"score": (int) This key contains the semantic analysis score of each category detected normalized to 100. All categories returned are determined to be relevant and the scores of each provide the weight of relevance in the content.

"origin": (string) This key contains the value "NORMAL" for the ADmantX Taxonomy categories recognized in the document and the value "VIRTUAL" for their ancestor categories from the Taxonomy hierarchy.

"parents": (array of strings) This key contains the list of "VIRTUAL" categories that are ancestors (parents, grandparents) of the category indicated in the key "name". This key will not be present for the top-level categories in the Taxonomy.

"type": (string) This key contains the value "TOPICS" identifying this JSON object as a semantic category. In essence it means the content is about the TOPIC identified by the "name" key.

Example of Categories Field in Response

The following is an example of the categories array returned in a response:

The "domain_categories" Key

• "domain_categories": (array of JSON objects) This key contains the list of domain categories detected about the domain of the requested URL. This key is only provided if the "domains" filter is authorized.

  Filter: domains

Each "domain_categories" array element returned contains:

"name": (string) This key contains the name of the category for the domain from the ADmantX Domain Taxonomy.

"origin": (string) This key contains the value "NORMAL" for the categories of the ADmantX Domains Taxonomy returned from the analysis of the domain of the page, and the value "VIRTUAL" for their ancestor categories from the Taxonomy hierarchy.

Example of domain_categories Field in Response

The following is an example of the keys found in the "domain_categories" array elements when there is a result for the domain:

The "domain_info" Key

• "domain_info": (string) This key contains the value "other" if the category of the domain is not yet included in the ADmantX Platform Service cache. It is empty when the domain category is returned from cache. This key is only provided if the "domains" filter is authorized.

  Filter: domains

Example of Domains "other" Response

The following is an example where the "domains" filter is authorized and enabled, and the result of the categorization of the domain for the requested URL is not yet available in cache. Note the empty "domain_categories" array and the value of "domain_info".

The "feelings" Key

• "feelings": (array of JSON objects) This key contains the list of contextual feelings (emotions) determined from the semantic analysis of the content.

  Filter: default or feelings or sentiment

Each "feelings" array element returned contains:

"name": (string) This key contains the name of the feeling from the ADmantX Taxonomy.

"score": (int) This key contains the semantic analysis score of each feeling detected normalized to 100. All feelings returned are determined to be relevant and the scores of each provide the weight of relevance in the content.

"origin": (string) This key contains the value "NORMAL" for the ADmantX Taxonomy categories actually recognized in the document and the value "VIRTUAL" for their ancestor categories from the Taxonomy hierarchy.

"parents": (array of strings) This key contains the list of "VIRTUAL" feelings that are ancestors (parents, grandparents) of the feeling indicated in the key

"type": (string) This key contains the value "FEELINGS" identifying this JSON object as a semantic feeling.

Example of Sentiment Only in "feelings" Field in Response

Note: If the "default" and "feelings" filters are disabled and the "sentiment" filter is enabled for the API key, then the "feelings" field will only contain sentiment categories. No other emotions categories will be provided.

The following is an example of the "feelings" field when the "default" and "feelings" filters are disabled, and the "sentiment" filter is enabled:

Example of "feelings" Field in Response

The following is an example of the "feelings" field in a response.

The "entities" Key

• "entities": (array of JSON objects) This key contains the list of entities (people, places, organizations, and main lemmas) extracted from the content.

  Filter: default or entities or geo (for the geographical information)

Each "entities" array element returned contains:

"name": (string) This key contains the name of the entity.

"score": (int) This key contains the score inferring the frequency of the entity in the text.

"origin": (string) The default value of this key is "NORMAL". This key is set to "VIRTUAL" only for the additional information added to the places when the request parameter "geo" is set to "true".

"parents": (array of strings) This key is present only when the filter "geo" is activated, and it refers only to the "place" entities retrieved in the content. The "parents" key contains a hierarchical list specifying the geographical position of such places retrieved in the content (e.g., in which region, country, and continent they are located).

"type": (string) This key contains the type of entity extracted. This key can be set to one of the following:

• "PLACES": The entity is a geographical location.

• "MAINLEMMAS": The entity is a main lemma, i.e., a noun, verb, adjective, adverb or a product identified by our semantic analyzer engine as relevant in the text.

• "ORGANIZATIONS": The entity is a company or organization.

• "PEOPLE": The entity is a person.

Example of "entities" Field in Response

The following is an example for the "entities" array in a response.

The "relations" Key

• "relations" - (array of key/value pairs) This key provides a list of "Subject", "Action", and "Object" related to the "Intentions" type.

  Filter: relations

Each "relations" array element contains:

• "name": (string) The name of the relation.

• "origin": (string) This is for future use ("NORMAL" for now).

• "relation": (JSON object) This key is a map containing:

  • "subject": (string) The subject of the action.

  • "action": (string) The identified action.

  • "object": (string) The object of the action.

• "type": (string) This key contains the value "INTENTIONS" identifying this JSON object as an intention.

Example of "relations" Field in Response

The following is an example for the "relations" array in a response.

The "admants" Key

• "admants": (array of key/value pairs) This key contains the list of admants (custom contextual segments), linked to the request API key, that are detected by the semantic analysis of the content.

  Filter: default or admants

Each "admants" array element returned contains:

• "name": (string) The name of the admant detected.

• "score": (string) The relevance of each admant in relation to the other admants recognized within the same document.

• "origin": (string) This key is always set to "ADMANTS".

• "type": (string) This key contains the value "ADMANTS" identifying this JSON object as a custom contextual segment.

• "targeting": (string) This key could contain 2 values: Avoidance or Contextual. Avoidance means that the segment must be used to avoid a specific content, Contextual means that the segment must be used to target a specific content.

• "unique_id": (int) This key contains the progressive unique identifier of the segment.

• "segment_type": (string) This key could contain several values: Seasonal, Vertical, Brand Safety Vertical, Custom, etc. It's just a descriptive field used to organize the segments returned. By default, the value "Custom" is assigned.

• "team": (int) This key contains the Team Id associated to the API key the segment is created for.

ADmantX Platform Service Response Examples

This section contains a number of examples of different response formats based on the value of the request key "decorator" (see decorator input key description in section API Input Description for details).

Example of the "other" Response in Asynchronous Environments

The following is an example of the "other" response from an asynchronous ADmantX Platform Service.

Note in the response the value of the "descriptor" key is "other."

Example of Response using "javascript" Decorator

The following depicts an example of a valid response using the "javascript.<decorator>" decorator:

Example of the "template" Decorator Response

The following depicts an example of a valid response using the "template.<decorator>" decorator.

Error Messages

If a problem occurs during the analysis of the content, the output key "valid" will contain the value "KO" and the output key "info" will contain the error description. The following table lists the error messages with their description.

Example of Invalid URL Extension Error Response

In the following example error response the reason is the URL requested to be analyzed contains an invalid extension that cannot be processed by the ADmantX Platform.

Note: For the purpose of the example the key value "test" is interpreted as a valid value.

Example of Invalid User ID (API Key) Error Response

In the following example error response the reason indicates the request was issued with an invalid "key" value "test".