targetAPI PCP API OVERVIEW

The targetAPI PCP (Predictive Content Personalization) Service API is a way for other organizations to use targetAPI's personalization and recommendation technology. It is offered as a hosted Web Service: targetAPI operates servers that provide these functions, and customers' servers talk to targetAPI servers to access these functions.

In a typical use-case, the customer has

  • many items in its database; these could be news articles, books, other products, videos, user generated content etc.

  • many people (users) viewing these items.

  • a wish to know which items are most relevant to each user. This is provided by PCP Service API.

Items

In order to do its work, PCP Service must have a list of items to recommend from, and a list of users for whom recommendations are needed. Both lists could potentially change over time, and a portion of the API deals with updating these lists so that their copies in the targetAPI database are up-to-date with corresponding information in the customer database. Each item must have a textual description (title, keywords, or other form of description) and this is sent to targetAPI servers; this is the basis of PCP Service recommendations -- e.g. items whose textual description is about snowboarding get recommended to people who are interested in snowboarding.

People

The predictive aspect of the technology works best if the customer sends the full names of people/users to targetAPI servers. The power of targetAPI technology lies in solving the "cold-start problem" of behavioral targeting, i.e. giving meaningful recommendations to new users who have no behavior history on customer's site. However targetAPI also learns from behavior: customer may optionally send feedback to targetAPI servers about which items were liked/disliked by specific users, and this is taken into account when serving subsequent recommendations to these users.


PCP Service API Technical Documentation

1. Introduction

2. Authentication

3. General API conventions

4. API operations

4.1 Managing Content Items

4.1.1 Adding or Modifying a Content Item

4.1.2 Deleting a Content Item

4.1.3 Getting Data About a Given Content Item

4.1.4 Getting a List of Content Items

4.2 Managing People

4.2.1 Creating or Modifying a Person

4.2.2 Deleting a Person

4.2.3 Getting a List of People

4.3 Requesting Recommendations

4.3.1 Simple Request for Recommendations

4.3.2 Modifying a Person and Requesting Recommendations

4.4 Giving Feedback on Recommendations

4.4.1 Submitting Feedback on Recommendations

4.4.2 Getting Ratings Given by a Person

4.4.3 Getting Ratings Given by a Person (floating-point version)

4.5 Getting a Person's Profiling Results

5. API Usage Limits and TOS

 


1. Introduction

PCP (Predictive Content Personalization) Service is a hosted web service that recommends content items to particular persons based on their relevance to this person's interests. Content items are provided by the user of API, as is data about people for whom recommendations are sought. This data is private to API user submitting it; other API users will not see it.

2. Authentication

Each API user has an Application Key, which is assigned to each API user by targetAPI. It is a text string consisting of 1..64 characters from the set [0-9A-Za-z_]. Application Key (appkey) is part of the URI in each API request. In examples used in this document, the Application Key is taken to be 0000000000000000. This is an example value only, each API user will have a different key.

3. General API Conventions

The API is HTTP-based and follows the REST style. The API endpoint is api.targetapi.com. That is, there are a number ofresources, each having an URI, and standard HTTP operations can be used to interact with the resource. For example, a content item has an URI http://api.targetapi.com/{appkey}/item/{itemid}, and HTTP POST operation on such URI will modify the content item, whereas HTTP DELETE operation on it will delete the content item.

Success or failure of each operation is indicated using the HTTP response status code, with 200 signifying success. 4xx response status codes mean that the API user (you) has done something wrong, and the response status text describes the reason. Exceeding the API usage limits of your appkey will also result in 4xx response codes. 5xx response status codes denote server internal error conditions. A valid API request will never receive a redirection (3xx) response.

Some operations have JSON-encoded data as their HTTP response body. Operations that return no data apart from the response code (e.g. DELETE) have empty HTTP response body.

In HTTP request parameters, Unicode text is converted to bytes using UTF-8 encoding. HTTP POST request body (parameters) is in application/x-www-form-urlencoded encoding.

Content item and person identifiers used in the API are chosen by API user (you). That is, when adding a content item or person, a HTTP POST is done, and the URI includes the identifier. A content item or person with such identifier is then created, and subsequent operations on that item/person use the same identifier. When creating a new item/person, API user should ensure that the identifier is not already in use, or else the existing item/person is modified instead of new one being created. Content items and persons use separate identifier namespaces; in other words, it is possible to create a person with the same identifier as a content item. The API supports any textual identifier, provided that it consists of 1..64 characters from the set [0-9A-Za-z_]. They are compared verbatim, case-sensitive.

4. API Operations

4.1. Managing Content Items

In order to provide recommendations, PCP Service must have a list of content items to recommend from. The list could potentially change over time, and this portion of the API deals with populating and updating it. Each content item should have a textual description (title, keywords, or other form of description) - the relevancy of this text to a person is the main basis of recommendations. An item with all empty textual description fields is technically allowed by the API, but it will be rarely/never recommended because relevancy is unclear.

4.1.1. Adding or Modifying a Content Item

HTTP operation: POST /{appkey}/item/{itemid}

POST parameters:

  • title - optional; Unicode text; only the first 255 characters are used
  • keywords - optional; Unicode text; only the first 255 characters are used. Individual keywords should be separated by commas
  • content - optional; Unicode text; only the first 10000 characters are used

targetAPI automatically recognizes the language of these textual description fields. Currently supported languages are English, German, Spanish, Portuguese, French, Italian, Dutch, Finnish, Estonian, Swedish, Hungarian, Latvian, Lithuanian, Polish, Romanian, Turkish.

When modifying an existing content item, the whole item is overwritten with new information, assuming empty strings for missing optional parameters.

No response body.

Example request using cURL:

curl -d "title=mytitle&keywords=photography,snowboarding&content=this is a content item about photography and snowboarding" "http://api.targetapi.com/0000000000000000/item/myitem1"

4.1.2. Deleting a Content Item

HTTP operation: DELETE /{appkey}/item/{itemid}

No parameters, no response body. Deletes a content item from the list, so it no longer appears in recommendations.

Example request using cURL:

curl -X DELETE "http://api.targetapi.com/0000000000000000/item/myitem1"

4.1.3. Getting Data About a Given Content Item

HTTP operation: GET /{appkey}/item/{itemid}

No parameters.

Response body: JSON-encoded object with these attributes:

  • id - text, exactly the same as provided to the API when that content item was added
  • title - Unicode text; the first 255 characters only
  • keywords - Unicode text; the first 255 characters only
  • content - Unicode text; the first 10000 characters only

Example request using cURL:

curl "http://api.targetapi.com/0000000000000000/item/myitem1"

Example response:

[

{

"keywords": "photography,snowboarding",

"content": "this is a content item about photography and snowboarding",

"id": "myitem1",

"title": "mytitle"

}

]

4.1.4. Getting a List of Content Items

HTTP operation: GET /{appkey}/items

No parameters.

Response body: JSON-encoded list of content items (in arbitrary order). Each item in the list has the following attributes:

  • id - text, exactly the same as provided to the API when that content item was added
  • title - Unicode text; the first 255 characters only

Example request using cURL:

curl "http://api.targetapi.com/0000000000000000/items"

Example response:

[

{

"id": "myitem1",

"title": "mytitle"

},

{

"id": "myitem2",

"title": "mytitle2"

}

]


4.2 Managing People

In order to provide recommendations, PCP Service must have a list of people to recommend to. The list could potentially change over time, and this portion of the API deals with populating and updating it.

4.2.1. Creating or Modifying a Person

HTTP operation: POST /{appkey}/person/{personid}

POST parameters:

  • name - optional; Unicode text; only the first 255 characters are used. The predictive aspect of the technology works only if the particular person record includes a full name, although it is technically optional
  • interests - optional; Unicode text; individual interests should be in English language and separated by commas
  • ip_location - optional; Unicode text. This could be the name of a city, state, country or other location; for example 'New York', 'Ireland', 'Frankfurt, Germany', 'San Francisco, CA, United States'
  • user_agent - optional; Unicode text. Some interests are inferred from the type of browser someone is using
  • email_addresses - optional; Unicode text. Whitespace-separated list of e-mail addresses belonging to this person
  • twitter_user_id - optional; Unicode text. This can be either a numerical user ID or Twitter screen name; e.g. both '691353' and 'Joi' will do
  • myspace_user_id - optional; Unicode text. Note that this is an user ID, not a screen name; e.g. '112385' and not 'joiito'

E-mail addresses and user IDs help telling the difference between the many John Smiths out there.

When no parameters are provided, the technology is reduced to learning this user's interests based on what content items they like (see Giving Feedback on Recommendations).

When modifying an existing person, the whole person data is overwritten with new information, assuming empty strings for missing optional parameters.

No response body.

Example request using cURL:

curl -d "name=Ansel Adams" "http://api.targetapi.com/0000000000000000/person/myperson1"

4.2.2. Deleting a Person

HTTP operation: DELETE /{appkey}/person/{personid}

No parameters, no response body. Deletes a person from the list, so no recommendations can be requested for them.

Example request using cURL:

curl -X DELETE "http://api.targetapi.com/0000000000000000/person/myperson1"

4.2.3. Getting a List of People

HTTP operation: GET /{appkey}/persons

No parameters.

Response body: JSON-encoded list of persons (in arbitrary order). Each person in the list has the following attributes:

  • id - text, exactly the same as provided to the API when that person was added
  • name - Unicode text; the first 255 characters only

Example request using cURL:

curl "http://api.targetapi.com/0000000000000000/persons"

Example response:

[

{

"id": "myperson1",

"name": "Ansel Adams"

},

{

"id": "myperson2",

"name": "Carola Presley"

}

]


4.3. Requesting Recommendations

These operations return recommendations for a given person. Only such content items that are deemed relevant to the person are returned, in the order of expected relevancy and popularity. If there are no content items deemed relevant to the person, no content items are returned.

4.3.1. Simple Request for Recommendations

HTTP operation: GET /{appkey}/person/{personid}/recommendations

GET parameters:

  • count - optional; integer. This is the maximum number of recommended content items wanted, default 30. Negative or zero value is interpreted as 1. The results could also contain fewer than wanted items, if there are fewer relevant content items available for the given person.
  • restrict_to_item_ids - optional; text; space-separated list of itemid's out of which the recommended items should be selected. Defaults to all content items.
  • exclude_items_rated_lower_than - optional integer, default 0; items this person has rated with rating_value less than this are excluded from recommendation. 0 (the default) means that negatively-rated items are excluded, -1 means that no items are excluded based on rating, +1 means negatively and neutrally rated items are excluded, and values > 1 mean all rated items are excluded.

Response body: JSON-encoded object with these attributes:

  • profile_completeness_percentage - integer, 0..100. After adding a person (or modifying their name) it takes a few seconds to complete profiling of this person. During this period, this attribute has a value less than 100; after this period, the value is 100.
  • recommendations - list of content item objects, ordered from most relevant to least relevant, each having these attributes:
    • id - text, exactly the same as provided to the API when that content item was added
    • title - Unicode text; the first 255 characters only

Example request using cURL:

curl "http://api.targetapi.com/0000000000000000/person/myperson1/recommendations?count=10"

Example response:

{

"profile_completeness_percentage": 100,

"recommendations": [

{

"id": "myitem2",

"title": "mytitle2"

},

{

"id": "myitem1",

"title": "mytitle"

}

]

}

4.3.2. Modifying a Person and Requesting Recommendations

This is a convenience operation that has the same effect as doing a POST /{appkey}/person/{personid} followed by GET /{appkey}/person/{personid}/recommendations. The person must already exist - this operation cannot be used to create new persons. The whole person data is overwritten with new information, assuming empty strings for missing optional parameters.

HTTP operation: POST /{appkey}/person/{personid}/recommendations

POST parameters:

  • count - optional; integer. This is the maximum number of recommended content items wanted, default 30. Negative or zero value is interpreted as 1. The results could also contain fewer than wanted items, if there are fewer relevant content items available for the given person.
  • restrict_to_item_ids - optional; text; space-separated list of itemid's out of which the recommended items should be selected. Defaults to all content items.
  • exclude_items_rated_lower_than - optional integer, default 0; items this person has rated with rating_value less than this are excluded from recommendation. 0 (the default) means that negatively-rated items are excluded, -1 means that no items are excluded based on rating, +1 means negatively and neutrally rated items are excluded, and values > 1 mean all rated items are excluded.
  • name - optional, defaults to empty string; Unicode text; only the first 255 characters are used
  • interests - optional, defaults to empty string; Unicode text
  • ip_location - optional, defaults to empty string
  • user_agent - optional, defaults to empty string
  • email_addresses - optional, defaults to empty string
  • twitter_user_id - optional, defaults to empty string
  • myspace_user_id - optional, defaults to empty string

Response body: JSON-encoded object with these attributes:

  • profile_completeness_percentage - integer, 0..100. After adding a person (or modifying their name) it takes a few seconds to complete profiling of this person. During this period, this attribute has a value less than 100; after this period, the value is 100.
  • recommendations - list of content item objects, ordered from most relevant to least relevant, each having these attributes:
    • id - text, exactly the same as provided to the API when that content item was added
    • title - Unicode text; the first 255 characters only

Example request using cURL:

curl -d "interests=politics,management,web 2.0" "http://api.targetapi.com/0000000000000000/person/myperson1/recommendations"

Example response:

{

"profile_completeness_percentage": 100,

"recommendations": [

{

"id": "myitem2",

"title": "mytitle2"

},

{

"id": "myitem1",

"title": "mytitle"

}

]

}


4.4. Giving Feedback on Recommendations

4.4.1. Submitting Feedback

HTTP operation: POST /{appkey}/person/{personid}/rating/{itemid}

This operation improves subsequent recommendations for a given person, by letting the recommender system know which content items the person has liked/disliked. Repeating this operation with the same person and item overwrites previous rating - i.e. ratings are not cumulative. The specified itemid does not necessarily have already appeared in recommendations for this person. Depending on the exclude_items_rated_lower_than parameter when requesting recommendations, items with some rating values will not appear in further recommendations to this person.

This operation is optional: recommendations can be generated also without providing feedback.

POST parameters:

  • rating_value - integer. All positive values are normalized to +1 and indicate liking of this content item, all negative values are normalized to -1 and indicate disliking. Zero value (which is default) indicates neutral opinion.
  • rating_value_float - float. Same as rating_value, but a float value bounded to -10..+10 range. This enables having different values for different types of user feedback (e.g. just reading a content item could give +0.5 rating, whereas "Liking" it could give +2 rating). If both rating_value and rating_value_float parameters are present, then rating_value_float is used and rating_value is ignored.

Example request using cURL:

curl -d "rating_value=1" "http://api.targetapi.com/0000000000000000/person/myperson1/rating/myitem1"

4.4.2. Getting Ratings Given by a Person

HTTP operation: GET /{appkey}/person/{personid}/ratings

No parameters.

Response body: JSON-encoded list of rated items (in arbitrary order). If the person has not rated anything (i.e. no POST /{appkey}/person/{personid}/rating/{itemid} request has not been done with this appid+personid combination) then the list is empty. Each item in the list has the following attributes:

  • id - text, exactly the same as provided to the API when that item was added
  • rating_value - integer; +1 indicates liking of this content item, -1 indicate disliking, 0 indicates neutral opinion

Example request using cURL:

curl "http://api.targetapi.com/0000000000000000/person/myperson1/ratings"

Example response:

[

{

"id": "myitem1",

"rating_value": 1

},

{

"id": "myitem2",

"rating_value": -1

}

]

 

4.4.3. Getting Ratings Given by a Person (floating-point version)

HTTP operation: GET /{appkey}/person/{personid}/ratings_float

No parameters.

Response body: JSON-encoded list of rated items (in arbitrary order). If the person has not rated anything (i.e. no POST /{appkey}/person/{personid}/rating/{itemid} request has not been done with this appid+personid combination) then the list is empty. Each item in the list has the following attributes:

  • id - text, exactly the same as provided to the API when that item was added
  • rating_value_float - float; positive values indicate liking of this content item, negative values indicate disliking, 0 indicates neutral opinion

Example request using cURL:

curl "http://api.targetapi.com/0000000000000000/person/myperson1/ratings_float"

Example response:

[

{

"id": "myitem1",

"rating_value_float": 0.5

},

{

"id": "myitem2",

"rating_value_float": -1.25

}

]


 

4.5 Getting a Person's Profiling Results

HTTP operation: GET /{appkey}/person/{personid}/profile

This operation returns profiling results: the topics the given person is likely to be interested in, and his/her likely gender. Most of the recommendation functionality is based on this profile. This operation requires special privileges attached to the appkey; not all API users are able to access it. If you would like to access this operation, please contact us at This e-mail address is being protected from spambots. You need JavaScript enabled to view it . If there are no such privileges, a HTTP response status 403 is returned.

No parameters.

Response body: JSON-encoded object with these attributes:

  • profile_completeness_percentage - integer, 0..100. After adding a person (or modifying their name) it takes a few seconds to complete profiling of this person. During this period, this attribute has a value less than 100; after this period, the value is 100
  • topics - list of topic objects, ordered from most relevant to least relevant, each having these attributes:
    • relevancy_percentage - floating point number, 0..100. Higher values mean the person is more likely to be interested in this topic
    • topic - Unicode text
    • subtopics - list of Unicode text objects; could be missing if the topic has no relevant subtopics
  • google_ad_categories - list of category objects, ordered from most relevant to least relevant, each having these attributes:
    • category - Unicode text, corresponding to one of 27 top-level Google advertising categories
    • relevancy_percentage - floating point number, 0..100. Higher values mean the person is more likely to be interested in this category
  • estimated_yearly_income_usd - integer, >= 0. This is an estimate of the persons yearly income in US dollars. The attribute is missing if income could not be guessed
  • estimated_naics_industry_codes - list of integers. This is a list of US Census Bureau's NAICS 2007 industry codes describing the persons work area. The attribute is missing if industry could not be guessed
  • gender - string, "M" or "F" (without quotes). This attribute is missing if gender could not be guessed
  • related_people - list of Unicode text objects with names of people likely to be friends or somehow related to the given person, ordered by descending relevancy. This attribute could be missing if no relevant people were found
  • agegroup_below20_percentage - floating point number, 0..100. Probability percentage that the person is less than 20 years old. This attribute is missing if age could not be guessed
  • agegroup_20to24_percentage - floating point number, 0..100. Probability percentage that the person is 20..24 years old. This attribute is missing if age could not be guessed
  • agegroup_25to34_percentage - floating point number, 0..100. Probability percentage that the person is 25..34 years old. This attribute is missing if age could not be guessed
  • agegroup_35to44_percentage - floating point number, 0..100. Probability percentage that the person is 35..44 years old. This attribute is missing if age could not be guessed
  • agegroup_over44_percentage - floating point number, 0..100. Probability percentage that the person over 44 years old. This attribute is missing if age could not be guessed

Example request using cURL:

curl "http://api.targetapi.com/0000000000000000/person/myperson1/profile"

Example response:

{

"profile_completeness_percentage": 100,

"gender": "M",

"estimated_naics_industry_codes": [

51913,

5415,

71392

],

"agegroup_below20_percentage": 10.34,

"agegroup_20to24_percentage": 22.21,

"agegroup_25to34_percentage": 32.78,

"agegroup_35to44_percentage": 23.10,

"agegroup_over44_percentage": 11.57,

"topics": [

{

"relevancy_percentage": 46.4904380962,

"topic": "Web 2.0",

"subtopics": ["Technorati", "Twitter", "Flickr"]

},

{

"relevancy_percentage": 20.1411351562,

"topic": "Outdoor recreation"

}

],

"google_ad_categories": [
{
"category": "Photography",
"relevancy_percentage": 38.465719996020198
},
{
"category": "Humanities",
"relevancy_percentage": 12.637477549111098
},
]
}


5. API Usage Limits and TOS

  • Customer can POST up to 5,000 persons/items in a day:
    • Creating or changing the data of an item or name of a person.
    • Requesting a recommendation with modifying the person's name.
    • Requests where the data of an item or name of a person is the same as already existing data are not counted towards the limit, deletions are also not counted towards the limit.
  • Customer can request up to 50 recommendations in a minute.
  • Customer can make 200 overall requests in a minute.
  • Customer can have up to 5,000 items
  • Customer can have up to 5,000 persons
  • Requesting a person's profiling results is an operation that requires special privileges.  Please contact us if you would like to request access to this operation.
  • Please also contact us if your application requires rate limits in excess of those listed above.
  • Your use of our API confirms that you have reviewed and agreed to the terms of our API Terms of Service.  Please click *here* to review the API Terms of Service.