Data Service Reference Guide

Important Things to Know

Before making a call to Primal’s Data Service, here are some helpful things to keep in mind:

  • Any call to the Data Service requires you provide your Primal username and password as part of the Basic HTTP Authentication headers in your call.
  • Any call to the Data Service also requires that you provide the following header values to identify the particular application you are making the call on behalf of:
    • Primal-App-ID – Your Primal application’s ID.
    • Primal-App-Key – Your Primal application’s key value.
  • All calls to the Data Service are throttled/rate-limited based on the particular plan that your application is on.

Managing Interest Graphs

Add a topic to an interest graph

To add a topic to an interest graph, send a POST request to Primal. Once Primal creates the topic, it begins to extend the topic with semantic terms to create an interest graph. You can retrieve all or part of that interest graph with a GET call (see Retrieve a topic (with filtered content) from an interest graph).

POST https://data.primal.com/{topic URI}

Store a topic in an interest graph

To store a topic in an interest graph but not have Primal perform any semantic expansion, use a PUT call. Primal will add the topic as a node in the interest graph, but not do any additional processing. If you want to add a topic and have Primal begin expanding the interest graph from that topic, use the POST call (see Add a topic to an interest graph).

PUT https://data.primal.com/{topic URI}

Retrieve a topic (with filtered content) from an interest graph

To retrieve a topic from an interest graph, use a GET call. Primal will also, by default, return a selection of content in the payload that is relevant to the topic requested. The content will come from the web and/or RSS source(s) defined in the user’s default content source (see Creating a content source).

As a convenience, if you make a GET call for a topic that does not exist in the interest graph, the GET call will also act as a PUT (see Store a topic in an interest graph) and store the topic in the interest graph, although no semantic expansion will be performed unless you POST the topic (see Add a topic to an interest graph).

GET https://data.primal.com/{topic URI}?{params}

The output of this call can be customized by using the following optional http header values and/or URL parameters with the call:

Optional HTTP Headers
Name Value
Accept application/json — Return output in JSON format (default)
application/rss+xml — Return output in RSS 2.0 format
Optional URL Parameters
Name Description
primal:contentScore:min Filters the result set by using Primal’s content score as a relevancy threshold. Specify a minimum acceptable primal:contentScore value. As you increase this value, fewer content items will be returned. Possible values range between 0 and 1. If you do not set this value, Primal uses 0.54 as a default.This parameter can be used in conjunction with primal:contentCount:max to filter results to a particular number of items that meet a minimum relevancy threshold.
primal:contentCount:max Filters the result set based on the number of content items you care about. Specify the maximum number of items in the result set.If the parameter is not specified, then the number of content items returned varies, limited to those with a content score greater than or equal to the value of primal:contentScore:min.This parameter can be used in conjunction with primal:contentScore:min to filter results to a particular number of items that meet a minimum relevancy threshold.

For example, to return a list of the top ten items that have a content score of at least 0.4, use the following expression:

https://data.primal.com/foo?primal:contentScore:min=0.4&primal:contentCount:max=10

You will receive a maximum of 10 content items, all of which must score 0.4 or greater, in your response.

lid Specifies a unique identifier for a user’s interest graph. Use this parameter to provide public access to a user’s interest graph for the purpose of sharing.A lid value is generated by Primal for each unique top-level concept in an interest graph and is found in the primal:responseInfo block of the JSON response.This parameter is useful for RSS readers (which often cannot provide authentication headers in their calls) or for bookmarking and sharing out Primal resources.
contentSource Use this parameter to specify a content source for the filtering operation. If this is omitted, Primal uses the authenticated user’s default content source.The value of this optional URL be given in the following format:

{Sources or PrimalSources}/{content source name}

e.g. Sources/MyCustomSourceName or PrimalSources/News

You can further filter the content results with wish to be returned by including these additional modifiers to the contentSource value:

  • {content source}+site:url — Returns only topics that are pages on the specified Web site. For example, www.nytimes.com or www.youtube.com.
  • {content source}+keywords:{word} — Returns only topics that contain the specified word value. Note: Keyword restriction is only guarenteed to work with the Primal ‘Web’ source.
  • {content source}+time:timeframe — Returns only topics that were published in the specified timeframe. Valid date range modifiers are “24hours”, “1week” and “1month”. Note that, presently, this argument only works with Primal’s “News” content source and will not do a time-based restriction of other Primal sources, or any user-created custom content sources.

    e.g. PrimalSources/News+time:1week — returns content no more than 1 week old from the Primal News source.

For more information about content sources, see Managing Content Sources.

timeOut Specifies a period of time (in seconds; maximum is 120) for Primal to wait before returning a response.If you specify a timeout, Primal returns results even if its work is still “In Progress”. If Primal can meet the maximum result quality (i.e. its work is “Complete” before the timeout occurs, then those results are returned when they become available.)If you do not specify a timeout, Primal returns the most valuable amount of information it can obtain within a reasonable time frame based on the available sources of content and the complexity of the interest graph you are using.

If you specify “max” as the timeout value, then Primal maximizes the amount of time (up to a fixed limit) to achieve the best quality result.

To see the status of Primal’s work on your request, see the primal:Status field in the primal:responseInfo block of your call. It has three possible values: Requested (your request has been received and is in queue), In Progress (Primal is processing your request), and Complete (Primal has completed processing your request).

Delete a Topic from the interest graph

To remove a topic from an interest graph, use a DELETE call. Other topics connected to the deleted topic are deleted as well, unless they are connected to other topics in the interest graph.

The only legal URL argument that can be provided with this call is the lid value.

DELETE https://data.primal.com/{topic URI}

Managing Content Sources

Create a new content source

You can create a new content source using both a POST or a PUT call. and specify a source name and the various Websites and RSS feeds that you want Primal to use. You can only create one new source per POST call. If you try to create a source name that already exists, Primal returns an error.

You can also include a Primal source as part of a custom user source. Note the Primal sources groups Reference and News being included in the sample code below.

The contents element of the JSON payload that defines the content source can contain up to 200 potential website and/or RSS sources (The sample call shown below includes five.)

Note: You can pass a “time” parameter that tells Primal to consider content that was published within the specified time period. Options are: “24hours”, “1week”, or “1month”.

POST https://data.primal.com/@Sources
Content-Type application/json
Sample Body {“ContentSourceName“: {“default”: true,

“contents”: {

“http://www.website1.com”: {},

“http://www.website2.com/subsection”: {},

“http://data.primal.com/@PrimalSources/Reference”: {},

“http://data.primal.com/@PrimalSources/News”: {

“time”: “1week”

},

“http://www.news.com/feed.rss”: {

“time”: “24hours”

}

}

}

}

Alternatively, you can create a new custom content source by importing an OPML file that outlines a collection of feeds. Using an OPML file requires a PUT command with a slightly different format than the POST shown above. Content sources created in this manner can not be created as a ‘default’ content source. In order to make a collection that originated from an OPML import act as the ‘default’ content source, you will need to make a second call to explicitly set it as the default, as described here.

If your OPML file contains a nested hierarchy of feeds, Primal will collapse the hierarchy to two levels of depth.

PUT https://data.primal.com/@Sources/{content source name}/contents
Content-Type text/x-opml
Sample Body <?xml version=”1.0″ encoding=”UTF-8″?><opml version=”1.0″><head>

<title>Sample RSS subscriptions</title>

</head>

<body>

<outline text=”News” title=”News”>

<outline type=”rss” text=”CNN” title=”CNN” xmlUrl=”http://rss.cnn.com/rss/cnn_topstories.rss” htmlUrl=”http://www.cnn.com/index.html?eref=rss_topstories”/>

<outline type=”rss” text=”ABC News” title=”ABC News” xmlUrl=”http://feeds.abcnews.com/abcnews/topstories” htmlUrl=”http://abcnews.go.com/”/>

</outline>

<outline type=”rss” text=”National Geographic” title=”National Geographic” xmlUrl=”http://www.nationalgeographic.com/rss/photography/photo-of-the-day” htmlUrl=”http://photography.nationalgeographic.com/photography/photo-of-the-day/”/>

<outline type=”rss” text=”Hack a Day” title=”Hack a Day” xmlUrl=”http://www.hackaday.com/rss.xml” htmlUrl=”http://hackaday.com”/>

</body>

</opml>

Add more sources to an existing content source

If you want to append to the list of external content sources that Primal will watch, use this POST call to specify additional Web sites or RSS feeds to add to this Primal content source.

POST https://data.primal.com/@Sources/{content source name}/contents
Content-Type application/json
Sample Body {“http://www.another-interesting-site.com”: {},”http://www.more-good-stuff.com”: {}

}

– or –

POST https://data.primal.com/@Sources/{content source name}/contents
Content-Type text/x-opml
Sample Body <?xml version=”1.0″ encoding=”UTF-8″?><opml version=”1.0″><head>

<title>Additional RSS subscriptions</title>

</head>

<body>

<outline type=”rss” text=”Another Site” title=”Another Site” xmlUrl=”http://www.another-interesting-site.com” htmlUrl=”http://www.another-interesting-site.com”/>

<outline type=”rss” text=”More Good Stuff” title=”More Good Stuff” xmlUrl=”http://www.more-good-stuff.com” htmlUrl=”http://www.more-good-stuff.com”/>

</body>

</opml>

Make a content source the ‘default’ source

Primal uses your default content source for any calls to the data service where you do not explicitly provide an alternate source to use for the call. You can set which content source Primal should consider your default one to be with this call.

POST https://data.primal.com/@Sources/{content source name}
Sample Body {“default”: true}

Replace the feeds within a content source

You can replace all existing values within a custom content source with PUT request. The payload can be provided in JSON or OPML formats, and will completely replace all of the sources stored within the name of the content source provided in the PUT’s URI.

If you replace an existing content source using this method, a 200 status code will be returned upon success. If you are creating a new content source using this method, a 201 status code will be returned upon success.

PUT https://data.primal.com/@Sources/{content source name}/contents
Content-Type application/json
Sample Body {“http://www.website1.com”: { },”http://www.website2.com/subsection”: { },

“http://data.primal.com/@PrimalSources/Reference”: { },

“http://data.primal.com/@PrimalSources/News”: {

“time”: “1week”

},

“http://www.news.com/feed.rss”: {

“time”: “24hours”

}

}

– or –

PUT https://data.primal.com/@Sources/{content source name}/contents
Content-Type text/x-opml
Sample Body <?xml version=”1.0″ encoding=”UTF-8″?><opml version=”1.0″><head>

<title>Sample RSS subscriptions</title>

</head>

<body>

<outline text=”News” title=”News”>

<outline type=”rss” text=”CNN” title=”CNN” xmlUrl=”http://rss.cnn.com/rss/cnn_topstories.rss” htmlUrl=”http://www.cnn.com/index.html?eref=rss_topstories”/>

<outline type=”rss” text=”ABC News” title=”ABC News” xmlUrl=”http://feeds.abcnews.com/abcnews/topstories” htmlUrl=”http://abcnews.go.com/”/>

</outline>

<outline type=”rss” text=”National Geographic” title=”National Geographic” xmlUrl=”http://www.nationalgeographic.com/rss/photography/photo-of-the-day” htmlUrl=”http://photography.nationalgeographic.com/photography/photo-of-the-day/”/>

<outline type=”rss” text=”Hack a Day” title=”Hack a Day” xmlUrl=”http://www.hackaday.com/rss.xml” htmlUrl=”http://hackaday.com”/>

</body>

</opml>

List all content sources

To list all of the custom content sources associated to your Primal account.

GET https://data.primal.com/@Sources

To list all of the default content sources available from Primal.

GET https://data.primal.com/@PrimalSources

Retrieve a content source

If you want to retrieve a specific custom content source associated to your Primal account so that you can inspect the Web sites and RSS feeds that it is configured to use, use this call.

This call is also useful when you plan on modifying a content source, because modification requires you to PUT the entire content source definition back, so you will likely first need to GET it using this call, make the modification to that data that you wish, and finally PUT the changed payload back.

GET https://data.primal.com/@PrimalSources/{name of Primal source}

-or-

GET https://data.primal.com/@Sources/{name of User source}

Delete a content source

Custom content sources that you have created can be deleted. You cannot delete any of the “@PrimalSources” content sources, however.

DELETE https://data.primal.com/@Sources/{content source name}

HTTP Status Codes

Here are the HTTP Status Codes that can return in response to any of these requests.

Status Code Description
200 Successful call (GET and DELETE)
201 Successful call (POST and PUT)
400 Bad request. The syntax of your request was invalid.
401 Application is not authorized to access the user’s account.
403 Application is not authorized to access Primal. Ensure that your username, password, application ID and application key values are correct.
404 The specified source doesn’t exist.
429 Application has reached its usage limit for the moment.
500 Internal server error. An unexpected problem has occured.
501 Feature not supported.