Trove API

Trove is the personalization and content engine of WaPo Labs. The Trove API provides basic text analytics services, URL lookup for news articles, as well as a constantly updated set of news around any topic, which we call a Trove channel. Trove.com is an example implementation of the API and a helpful interface for creating or tuning Trove channels. Find WaPo Labs at wapolabs.com!

GET resources/{id}

Given a resource ID, retrieve the associated metadata.

Request URL

http://api.washingtonpost.com/trove/v1/resources/{id}[?include_variants][&callback]&key=<Your developer key>

Parameters

include_variants boolean Optional. Return variant forms for specified resources. Valid values are 0 (default) or 1.
callback string Optional. The name of your callback function if using JSONP.
id* number The resource ID, for example as returned from the /analysis call.

Example Query

http://api.washingtonpost.com/trove/v1/resources/4113518?key=

Code samples

Response 200

Returns the resource along with the status of the response.

Response body example

Content-Type: application/json

  1. {
    • "resource" : {
      • "id" : 4113518,
      • "name" : "Barack Obama",
      • "subtype" : "person",
      • "type" : "entity"
      • },
    • "status" : {
      • "code" : "200",
      • "message" : "OK"
      • }
    • }

GET resources

This call allows you to lookup a Trove resource ID by name or variants of the name, including partial matches.

Request URL

http://api.washingtonpost.com/trove/v1/resources[?variant][&include_completions][&resource_type][&limit][&include_variants][&resource_subtype][&callback]&key=<Your developer key>

Parameters

variant string Required. The name variant to match. If using searching for substring match, you must set the 'include_completions' flag to 1. Examples: "variant=obama", "variant=oba*&include_completions=1"
include_completions boolean Optional. Specifies that the supplied variant string is considered a substring match for the variant forms of resource names. Valid values 1 or 0 (default).
resource_type string Optional. A constraint on the type of resource. Default 'entity'. Available options: 'entity', 'category', 'source', 'feed'.
limit number Optional. The number of items to return. (default 20)
include_variants boolean Optional. Return variant forms of the names of matching resources. Valid values 0 (default) or 1.
resource_subtype string Optional. A constraint on the subtype of resource. Available options: 'event', 'award', 'title', 'peoples', 'organization', 'product', 'person', 'company', 'generic', 'place', 'concept'.
callback string Optional. The name of your callback function is using JSONP.

Example Query

http://api.washingtonpost.com/trove/v1/resources?variant=Obama&include_completions=1&key=

Code samples

Response 200

Response body example

Content-Type: application/json

  1. {
    • "resources" : [
      • {
        • "id" : 4113518,
        • "name" : "Barack Obama",
        • "subtype" : "person",
        • "type" : "entity"
        • },
      • {
        • "id" : 4114508,
        • "name" : "Michelle Obama",
        • "subtype" : "person",
        • "type" : "entity"
        • },
      • {
        • "id" : 4173586,
        • "name" : "Sasha Obama",
        • "subtype" : "person",
        • "type" : "entity"
        • },
      • {
        • "id" : 4173587,
        • "name" : "Malia Obama",
        • "subtype" : "person",
        • "type" : "entity"
        • },
      • {
        • "id" : 4194909,
        • "name" : "Will Obama",
        • "subtype" : "person",
        • "type" : "entity"
        • },
      • {
        • "id" : 4214565,
        • "name" : "Obama's Council of Economic Advisers",
        • "subtype" : "organization",
        • "type" : "entity"
        • },
      • {
        • "id" : 4218296,
        • "name" : "George Obama",
        • "subtype" : "person",
        • "type" : "entity"
        • },
      • {
        • "id" : 4258815,
        • "name" : "Obama Administration",
        • "subtype" : "organization",
        • "type" : "entity"
        • },
      • {
        • "id" : 4263925,
        • "name" : "Obama campaign",
        • "subtype" : "concept",
        • "type" : "entity"
        • },
      • {
        • "id" : 4263926,
        • "name" : "Obama donor",
        • "subtype" : "concept",
        • "type" : "entity"
        • },
      • {
        • "id" : 4263927,
        • "name" : "Obama aide",
        • "subtype" : "concept",
        • "type" : "entity"
        • },
      • {
        • "id" : 4267655,
        • "name" : "Obama For America",
        • "subtype" : "organization",
        • "type" : "entity"
        • }
      • ],
    • "status" : {
      • "code" : "200",
      • "message" : "OK"
      • }
    • }

GET channels/{id}/result

Returns the 10 most relevant, recent articles for a given channel ID, including article metadata like title, URL, snippet and related channels. You can find channels by using the /items call to lookup the channel IDs for a news article, or you can use Trove.com to make or discover your own channels.

Request URL

http://api.washingtonpost.com/trove/v1/channels/{id}/result[?content_set][&callback]&key=<Your developer key>

Parameters

content_set string Specifies which content is a candidate for return. A value of "trove" will return all aggregated content; a value of "socialreader" will return content from Trove Content Partners only.
id* number The id of the channel.
callback string Optional. The name of your callback function is using JSONP.

Code samples

Response 200

Response body example

Content-Type: application/json

  1. {
    • "status": {
      • "message": "OK",
      • "code": 200
      • },
    • "result": {
      • "totalItems": 52,
      • "items": [
        • {
          • "updated": "2013-05-15T04:11:16",
          • "displayName": "Nationals’ Bryce Harper gets stitches, bruises after colliding with wall; X-rays negative",
          • "url": "http://www.washingtonpost.com/sports/nationals/nationals-bryce-harper-gets-stitches-bruises-after-colliding-with-wall-x-rays-negative/2013/05/14/f5c4cdb4-bcdb-11e2-9b09-1638acc3942e_story.html?wprss=rss_sports",
          • "published": "2013-05-15T01:38:08",
          • "source": {
            • "url": "http://washingtonpost.com/",
            • "displayName": "The Washington Post",
            • "id": 5015841,
            • "objectType": "source"
            • },
          • "snippet": "The <em>Nationals</em> and Harper survived another scare. X-rays on his knee and shoulder, taken late Monday night...",
          • "authors": [
            • {
              • "displayName": "Adam Kilgore",
              • "id": "8000251",
              • "objectType": "author"
              • }
            • ],
          • "objectType": "item",
          • "id": "Lxfns",
          • "relatedChannels": [
            • {
              • "displayName": "Bryce Harper",
              • "id": 127319,
              • "objectType": "channel"
              • },
            • {
              • "displayName": "Washington Nationals",
              • "id": 5302,
              • "objectType": "channel"
              • }
            • ],
          • "itemType":"article"
          • }
        • ],
      • "computed":"2013-05-15T04:53:36",
      • "relatedChannels": [
        • {
          • "displayName": "Bryce Harper",
          • "id": 127319,
          • "objectType": "channel"
          • }
        • ],
      • "objectType": "channelResult"
      • }
    • }

GET items/{id}

For a given Trove item, find the corresponding URL, source, author, and related channels.

Request URL

http://api.washingtonpost.com/trove/v1/items/{id}[?callback]&key=<Your developer key>

Parameters

callback string The name of the JSONP callback function.
id* string

Code samples

Response 200

Response body example

Content-Type: application/json

  1. {
    • "status": {
      • "message": "OK",
      • "code": 200
      • },
    • "item": {
      • "id": "MEElA",
      • "objectType": "item",
      • "updated": "2013-04-10T01:35:05",
      • "displayName": "Google expanding super-fast Internet service to Austin",
      • "url": "http://www.washingtonpost.com/business/technology/google-expanding-super-fast-internet-service-to-austin/2013/04/09/7c70e8ae-a146-11e2-be47-b44febada3a8_story.html?wprss=rss_technology",
      • "published": "2013-04-10T00:08:00",
      • "source": {
        • "url": "http://washingtonpost.com/",
        • "displayName": "The Washington Post",
        • "id": 5015841,
        • "objectType": "source"
        • },
      • "authors": [
        • {
          • "displayName": "Cecilia Kang",
          • "id": "8000168",
          • "objectType": "author"
          • }
        • ],
      • "relatedChannels": [
        • {
          • "displayName": "Google",
          • "id": 16647,
          • "objectType": "channel"
          • }
        • ]
      • }
    • }

GET items

For a given URL, find the corresponding Trove item, source, author and related channels.

Request URL

http://api.washingtonpost.com/trove/v1/items[?url][&callback]&key=<Your developer key>

Parameters

url string The url of an article to lookup.
callback string The name of the JSONP callback function.

Code samples

Response 200

Response body example

Content-Type: application/json

  1. {
    • "status": {
      • "message": "OK",
      • "code": 200
      • },
    • "items": [
      • {
        • "id": "MEElA",
        • "objectType": "item",
        • "updated": "2013-04-10T01:35:05",
        • "displayName": "Google expanding super-fast Internet service to Austin",
        • "url": "http://www.washingtonpost.com/business/technology/google-expanding-super-fast-internet-service-to-austin/2013/04/09/7c70e8ae-a146-11e2-be47-b44febada3a8_story.html?wprss=rss_technology",
        • "published": "2013-04-10T00:08:00",
        • "source": {
          • "url": "http://washingtonpost.com/",
          • "displayName": "The Washington Post",
          • "id": 5015841,
          • "objectType": "source"
          • },
        • "authors": [
          • {
            • "displayName": "Cecilia Kang",
            • "id": "8000168",
            • "objectType": "author"
            • }
          • ],
        • "relatedChannels": [
          • {
            • "displayName": "Google",
            • "id": 16647,
            • "objectType": "channel"
            • }
          • ]
        • }
      • ]
    • }

GET topitems

Given a Trove User ID and content set, retrieve personalized recommendations. This call is in beta and we recommend you reach out to WaPo Labs for guidance on how to implement.

Request URL

http://api.washingtonpost.com/trove/v1/topitems[?limit][&content_set][&user_id][&callback]&key=<Your developer key>

Parameters

limit number The number of items to return.
content_set string The name of the content set form which to pick recommendations.
user_id string The id of the user on whose behalf the recommendations are generated.
callback string Optional. The name of your callback function is using JSONP.

Code samples

Response 200

Response body example

Content-Type: application/json

  1. {
    • "status": {
      • "message": "OK",
      • "code": 200
      • },
    • "topitems": [
      • {
        • "reasons": [
          • {
            • "type": "topical"
            • }
          • ],
        • "item": {
          • "updated": "2013-05-02T15:33:45",
          • "usageRights": "full",
          • "displayName": "Immigration and Employment: The Case of Professional Basketball",
          • "published": "2013-05-02T15:33:45",
          • "source": {
            • "url": "http://www.slate.com",
            • "displayName": "Slate",
            • "id": 5000391,
            • "objectType": "source"
            • },
          • "snippet": "and Ibaka and all the foreign-born <em>San Antonio Spurs</em> then the Heat will definitely win and it'll be boring",
          • "url": "http://www.slate.com/blogs/moneybox/2013/05/02/nba_and_skilled_immigration_does_serge_ibaka_cost_jobs.html",
          • "authors": [
            • {
              • "displayName": "Matthew Yglesias",
              • "id": "8002855",
              • "objectType": "author"
              • }
            • ],
          • "id": "16M72",
          • "relatedChannels": [
            • {
              • "displayName": "NBA Basketball",
              • "id": 16810,
              • "objectType": "channel"
              • }
            • ],
          • "objectType": "item"
          • }
        • }
      • ]
    • }

/streams

Returns a list of the streams owned by the given user.

Request URL

http://api.washingtonpost.com/trove/v1/streams[?user_id]&key=<Your developer key>

Parameters

user_id* string The id of the user whose streams are to be returned.

Code samples

Response 200

Returns the operation status plus a list of stream objects.

/streams/{id}/result

Returns the results of the stream, with recently picked items in the front of the result before algorithmically generated results.

Request URL

http://api.washingtonpost.com/trove/v1/streams/{id}/result[?limit]&key=<Your developer key>

Parameters

id* string
limit number The number of items to return (max 50).

Code samples

/streams/{id}/postedItems

Returns items picked by the curator in the given trove.

Request URL

http://api.washingtonpost.com/trove/v1/streams/{id}/postedItems[?limit]&key=<Your developer key>

Parameters

id* string The id of the stream.
limit number The number of items to return (default 10).

Code samples

/streams/{id}/pickedItems

Returns items picked by the curator in the given trove.

Request URL

http://api.washingtonpost.com/trove/v1/streams/{id}/pickedItems[?limit]&key=<Your developer key>

Parameters

limit number The number of items to return (default 10).
id* string The id of the stream.

Code samples