PRODUCT
Follow

Introduction

The Peer39 API allows 3rd party application developers to write to the Peer39 API service. The response that the API provides is designed to be read, extracted, and parsed by an application built by the client. This document provides the technical integration steps required to write to the Peer39 API service and an overview of the Peer39 technology.

There are two data centers in the US (East coast and West coast) and one in Europe. Traffic from these regions can expect response times lower than 200 ms. There is also a data center in Asia that supports APAC traffic with typical response times of less than 250 ms.

When there is sufficient information available on a page, the API response includes multiple values, represented by Category IDs, that indicate one or more of the five data channels. Please refer to About Peer39 and Categorization and the API Integration FAQs for more details.

  • Contextual categories: Describe content of the page (for example, Automotive).

  • Quality attributes: Describe the structure of the page (for example, CRE).

  • Safety attributes: Describe the safety of the page (for example, Safe from Mature).

  • Mobile App categories: Provide mobile app characteristics (for example, Mobile Apps : Content Advisory Rating : Rated Everyone).

  • Weather attributes: Provide the local weather condition based on the user's geo-location (for example, Weather: Conditions: Cloudy). For more information, see Peer39 Weather API Extension.

Peer39 API Technology Overview

Peer39 returns a response for every URL received. It is recommend that you send all your traffic to Peer39 and use the RT parameter to distinguish the Response Type. Your application should call the Peer39 service with every URL until you receive Final response (RT=0) is received successfully. The Final Response for a URL is cached in our system for 24 hours. If that URL is sent again within the 24 hours Time-To-Live (TTL), it gets the same Final Response classification result; after that time frame, the URL's Time-To-Live resets. When the system sees the URL again from that account, the system treats it as a new URL and classifies it again. Once the Response Type changes to RT=0, clients can cache the classification result as well. For more information, see Client-Side Cache Tips.

Our technology includes a URL-cleaning algorithm, which is applied on every URL request before URLs are processed for classification. There is a First Look response (RT=2) or a Failed response (RT=1) when the system sees a URL for the first few times. After receiving the First Look response (RT=2) and upon subsequent requests, the system processes the URL offline and the URL receives the full semantic classification or Final response (RT=0).

Response Type

Status

Meaning

RT=2

Pending

RT=2 is the First Look response. The First Look functionally does an initial analysis of the URL string to provide a general classification when applicable.

There are two types of First Look responses:

  • First Look Classification: A category that provides a general classification of the URL based on statistical information that the Peer39 system has on similar pages (for example, the system categorizes a page URL from Fox News as News for the first look category).

  • First Look Default: A generic URL category for which the system has no information (for example, Other).

RT= 1

Failed

RT=1 is a Failed response for URLs that had a technical problem, like a missing protocol or invalid URL.

RT= 0

Done

RT=0 is the Final response. It indicates that the page URL has been processed for a full page level semantic classification.

Implementation Requirements

  • The technical nature of the API implementation requires an engineering resource to be involved, along with a technical lead contact to manage the integration.

  • The client machine that runs the application to call the Peer39 service should allow the use of port 8080.

  • Peer39 technology must be able to access the URL to analyze the content and classify it. Requests can fail if there is a technical issue with the URL as shown in the following examples:

    URL Example

    Reason for Unacceptable URL

    http://NOPAGEURLSPECIFIED

    Page URL not specified.

    http://{referrer_url}

    Referrer URL not specified.

  • All requests should have a valid URL, with a valid protocol prefix and domain name like http://www.sitename.com; otherwise, the request will fail because the protocol is missing.

Interface Specification

Peer39 API: You can use basic HTTP to access the Peer39 API.

Peer39 Service: You can access the Peer39 Service by using a simple HTTP request, including the required parameters as part of the query string. Two common methods are supported: HTTP GET and HTTP POST. For speed and efficiency, we recommend using HTTP GET. It is faster than HTTP POST. When using this method, you must encode the URL when passing it in the pu parameter.

Request Format

This section includes structures and examples for API requests.

Standard Page-Level URL

Structure:


http://hostname.api.peer39.net/proxy/targeting?cc=clientCode

&pu=[PageURL]&mo=&ct=[c_customvalue]&rc=[requestcount]

            

Example:

 
http://acmeadvertising.api.peer39.net/proxy/targeting?

cc=NwK8OehiC9cSJEcpby6fbowEVshWUO5xu1soA45ThuI33=
&pu=http://money.cnn.com/2014/10/08/investing/tesla-d-stock/index.html
&mo=&ct=c_InventorySourceID123&rc=1587

            

Mobile App

Mobile App Structure:


http://hostname.api.peer39.net/proxy/targeting?cc=clientCode&pu=

&mo=[appID;mobileOS]&ct=[c_customvalue]&rc=[requestcount]

            

Mobile App Example:


http://acmeadvertising.api.peer39.net/proxy/targeting?
cc=NwK8OehiC9cSJEcpby6fbowEVshWUO5xu1soA45ThuI33=&pu=
&mo=com.pandora.android;android&ct=c_InventorySourceID123&rc=1587

            

Considerations

The API call should contain ALL Peer39 API Inputs and Parameters.

While some of the parameters do not require values, it is a best practice (and highly recommended) to populate as many of the parameters for which you currently have values at this time and continue doing so as more values become available to you. In doing so, enhancements and future categories such as Event Based Targeting categories (for example, stock market conditions) can be added to your account.

Even if no value is set or available for a particular parameter, please ensure that the parameter and its accompanying '=' are included in the API call. Omitting any of the API call parameters will likely result in a broken API call and an Error (RT=1) response.

Example


http://acmeadvertising.api.peer39.net/proxy/targeting?
cc=NwK8OehiC9cSJEcpby6fbowEVshWUO5xu1soA45ThuI33=
&pu=http://money.cnn.com/2014/10/08/investing/tesla-d-stock/index.html

&mo=&ct=&rc=1
            

API Request Inputs and Parameters

Inputs & Parameters

Description

Syntax

Notes

Hostname*

Peer39 provides the hostname.

http://acmeadvertising.api.peer39.net/proxy/ targeting?

cc* (Client_Code)

Peer39 provides the Client Code or API Key; this parameter is a unique identifier for the account.

NwK8OehiC9cSJEcpby6fbowEVshWUO5xu1 soA45ThuI33=

pu* (Page_URL)

URL sent for classification; should be passed in the pu parameter.

If using HTTP GET, which is recommended, this value should be encoded.

Note: No pu= value is required or passed if you are using the mo= parameter for mobile app classification.

&pu=http://money.cnn.com/2014/10/08/investing/tesla-d-stock/index.html

&pu=http%3A%2F%2Fmoney.cnn.com%2F2014%2F10%2F08%2Finvesting%2Ftesla-d-stock%2Findex.html

URL must have valid:

  • Protocol: http:// or https://

  • Domain extension

mo** (Mobile App ID and Mobile OS)

Mandatory for Mobile App classification and targeting.

Holds iTunes or Google Play App ID, and mobile OS.

Note: When populating the mo= parameter, a pu= value should not be passed and the pu= parameter should remain empty. If you do pass a pu= value along with a mo= value, Peer39 will provide classification and response based solely on the pu= input value.

iTunes Item ID: &mo=284035177;ios

Google Play Bundle ID (case sensitive): &mo=com.pandora.android;android

iTunes or Google Play Mobile App IDs and Mobile OS.

  • App ID: iTunes Item ID or Google Play Bundle ID.

  • OS: Must be either android or ios. As of now, no other OS is supported. OS value must be lowercase.

ct (Custom_Value_Parameter)

Custom value parameter that can be used to pass a custom reporting value, such as Inventory source ID.

Custom alpha-numeric value preceded by c_.

&ct=c_InventorySourceID123

rc (Request Count)

Holds the Impression or Bid Request Count for the submitted URL/Page or Mobile App.

Numerical value representing the Impression or Bid Request Count for the URL/Page or Mobile App that is being submitted for classification.

&rc=1587

The rc value MUST contain a numerical value; it cannot be left empty.

*Mandatory API request Inputs and Parameters. If any are missing or syntax is incorrect, the result is a broken API call and/or Error Response (RT=1).

**Mandatory for Mobile App Categories.

Response Format

Peer39 provides classification results in our Short Response format. For more information about the overall structure and specific details of the Peer39 Short Reponse, see Peer39 Short Response Format.

Short Reponse Structure

Version#RT;LNGCODE#CID:SCORE;CID:SCORE#ADSTATS#

Short Response Example

004#0;en#7794:100;7890:63;7891:63;7906:64;12931:64;#4-6;1:A,7:C#

Note: Periodically, Peer39 will add new data attributes to the offering, and these will most often be released as new Categories. Peer39 recommends building your application in a way that allows for easy:

  • Addition of new categories.

  • Potential modification of existing categories such as updating or revising naming convention.

  • Removal of old or undesired categories.

Peer39 may also release new attributes as a new variable within the response, as was the case with Ad Stats. If we release additional attributes as a new variable, which will alter the structure of the response, we will not automatically add it to the current response version that you use. We will alert you to the change and coordinate with you so that you can take advantage of the new offering.

Passing Additional Variables

In some cases, you may want to pass to Peer39 a unique identifier to be used for reporting purposes. An example would be for a DSP to pass a supply source, like a site ID, to be reported on independently from another. This would be useful for us to provide comparisons of contextual, page quality or brand safety attributes between supply sources. You would use the CT parameter in the query string to accomplish this, where c_ID1 is variable 1 or SiteID1.


http://hostname.api.peer39.net/proxy/targeting?
cc=clientCode&pu=PageURL&mo=&ct=c_customvalue&ge=countrycode;state;city
&ll=coordinate;coordinate&zp=postalcode&ip=ipaddress
          

Details regarding the ct parameter can be found in the API Request Inputs & Parameters.

Testing

The Peer39 API Sandbox will enable your development resource to build an application against our API and test the Peer39 service. The API sandbox has a limit of 1000 Queries Per Second limit per day, which should not be exceeded and access is provided for a limited time frame.

The Sandbox Taxonomy is Peer39’s generic taxonomy. It includes Peer39’s contextual, safety and quality attributes. The Production Account will have a similar taxonomy with the same naming convention except with different Category IDs.

To test latency see Test Latency.

Please contact our Business Development team for further details to get access to the API Sandbox keys.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments