targetAPI PCP API OVERVIEWThe 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
ItemsIn 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. PeopleThe 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. Introduction2. Authentication3. General API conventions4. API operations4.1 Managing Content Items4.1.1 Adding or Modifying a Content Item4.1.2 Deleting a Content Item4.1.3 Getting Data About a Given Content Item4.1.4 Getting a List of Content Items4.2 Managing People4.2.1 Creating or Modifying a Person4.2.2 Deleting a Person4.2.3 Getting a List of People4.3 Requesting Recommendations4.3.1 Simple Request for Recommendations4.3.2 Modifying a Person and Requesting Recommendations4.4 Giving Feedback on Recommendations4.4.1 Submitting Feedback on Recommendations4.4.2 Getting Ratings Given by a Person4.5 Getting a Person's Profiling Results5. API Usage Limits and TOS
1. IntroductionPCP (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. AuthenticationEach 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 ConventionsThe 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 Operations4.1. Managing Content ItemsIn 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 ItemHTTP operation: POST /{appkey}/item/{itemid} POST parameters:
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 ItemHTTP 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 ItemHTTP operation: GET /{appkey}/item/{itemid} No parameters. Response body: JSON-encoded object with these attributes:
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 ItemsHTTP 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:
Example request using cURL: curl "http://api.targetapi.com/0000000000000000/items" Example response: [ { "id": "myitem1", "title": "mytitle" }, { "id": "myitem2", "title": "mytitle2" } ] 4.2 Managing PeopleIn 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 PersonHTTP operation: POST /{appkey}/person/{personid} POST parameters:
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 PersonHTTP 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 PeopleHTTP 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:
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 RecommendationsThese 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 RecommendationsHTTP operation: GET /{appkey}/person/{personid}/recommendations GET parameters:
Response body: JSON-encoded object with these attributes:
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 RecommendationsThis 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:
Response body: JSON-encoded object with these attributes:
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 Recommendations4.4.1. Submitting FeedbackHTTP 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. The specified itemid does not necessarily have already appeared in recommendations for this person. This operation is optional: recommendations can be generated also without providing feedback. POST parameters:
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 PersonHTTP 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:
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.5 Getting a Person's Profiling ResultsHTTP 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:
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": [ 5. API Usage Limits and TOS
∞ |
