Tutorial

In the sections that follow, we’ll take you step-by-step through the basics of building a Primal-powered application. We’ll start with a few general concepts about the API and instructions for making programmatic calls.

General Concepts: Interest Graphs, Content Sources, and Users

Primal’s artificial intelligence creates interest graphs and filters your trusted sources of content.

Primal process
Interest graphs are representations in data of people and the things that they are interested in. We use these interest graphs to organize content from across the web, surfacing the items that are most relevant to each user’s interests.

An important difference with Primal is that we treat users as individuals. We create and maintain individual interest graphs for every user. As detailed below, you get to decide what constitutes a “user”, which may be an individual person or persona, a group of people, or a target audience.

Using the API, you manipulate these three main levers of control:

  1. The target user (identified with a Primal account and optionally, a user identifier of your choosing);
  2. the context for the user’s interest (such as their search queries, the URLs they read, or topics associated with their profiles); and
  3. the sources of content you want to organize and recommend to the user (such as a news article or a video).

Every time you provide new topics or objects of interest, Primal’s artificial intelligence generates data that describes those interests. It then filters your content sources using this interest data, highlighting the content that is most relevant to your users. With each interaction, Primal learns more about what matters to your users and the information they need.

Authentication and Application Identification

Primal associates its data with a Primal account. To access this data, you must include user authentication information in the header of your requests.

When you make calls to the API, you tell Primal which account to use with Basic HTTP authentication. Include the account username and password in the call header, and you can access the data for that account.

Along with identifying the user whose interest graph you want to access, you must also identify your application by including these two elements in a custom header when you make the call:

  • Primal-App-ID= Your application ID
  • Primal-App-Key= Your API key

To create and manage your Application ID/Key values, see the My Applications page, in your profile.

Multiple users can be created under each Primal account for a more fine-grained segmentation of your audience. To identify a user to our system, simply append a user identification string with each call to our API.

?uid={your-user-id}

You can identify a user using whatever audience description you like. For example:

  • ?uid=user1234 A user ID within your system
  • ?uid=user1234-work The “work” persona for a particular user
  • ?uid=MyCustomers A segment of your target customers
  • ?uid=@TwitterAccount A social media identity
  • ?uid=MyAppUsers Your mobile app users

Interacting with the Primal API

Primal works on-demand, in real-time, to handle the most demanding online and social media environments. As a cloud API, there’s no software to install or configure.

Use our interactive documentation to try out these examples.

Primal’s API is accessed on the web using a secure HTTPS protocol:
https://api.primal.com
Our software is constantly evolving, so we maintain different versions of the API to provide some stability for your integrations.
https://api.primal.com/v2
There are three main resources that are accessed through our API. To access these resources, simply append them to the URL:

  1. https://api.primal.com/v2/recommendations
  2. https://api.primal.com/v2/data
  3. https://api.primal.com/v2/extraction

You use the API to interact with Primal using standard HTTP request methods, such as POST and GET.

For example, to request recommendations for a user, you use the GET method:
GET https://api.primal.com/v2/recommendations
The responses returned by Primal’s API are formatted in JSON.

Based on the topics and parameters you include with each request, you can retrieve as much or as little information as you need. The specific features and number of calls you can make to Primal’s API are based on the pricing plan associated with your application.

Now that you’re set up to make requests to Primal’s API, let’s explore how to integrate Primal within your application.

Integrating Primal With Your App

How Primal Works

The best advanced technologies are simple to use. Building Primal-powered applications is literally as simple as 1-2-3.

Step #1 — Connect user interactions

Primal’s artificial intelligence generates an interest graph using the interactions of your end-users, acquired in real-time as they’re expressing their interests. Primal supports a range of interactions, from keywords and queries, to documents, URLs, and user profiles, creating a unique interest graph for each individual user. Using these basic input types, virtually any user interaction may be connected to Primal.

Primal interaction types, recommended interfaces, and examples.

Input Type User Interface Input Example
Topics Tags /main+topic/sub-topic1
Search Query Search Box /?q=my+search+query
URL Link-clicks /u=http%3A%2F%2Fmysite%2Findex.html
Text Messages ?t=this%20is%20my%20text%20message

Step #2 — Content targeting

Primal uses these interest graphs to filter the trusted content sources you choose, delivering highly targeted content recommendations.

Out-of-the-box, Primal will select content representing a wide range of sources and media types (such as News, Videos, etc.). For more fine-grained control, you can specify the content types, sources, and even the individual website you’d like to use. By combining these content targeting parameters, you have pinpoint control over the content that’s recommended to your audience.

Primal content types, sources, and examples.

Parameter Description Input Example
Media Type News articles, webpages, videos, etc. ?type=NewsArticle
Content Source The content aggregator used to retrieve the content ?contentSource=Primal
Content Collection The collection of content from a source contentCollection=Twitter+Popular
Website domain A URL pattern to target a website site=cnn.com/politics

Step #3 — Display targeted content

Primal returns the targeted content, ranked, cleaned and structured in a standardized, consistent format, making it easy to incorporate the personalized content into your website, app, bot, or intelligent system.

The nature of each response is dictated by the resource you’re calling (/extraction, /recommendations, or /data) and the optional parameters you include to tailor each response.

See our documentation for complete descriptions of our API parameters and responses.

Putting It All Together

We now have all the elements to create our first Primal-powered app. For this tutorial, we’ll use one of the simplest Primal apps you can build, a personalized news app.

We’ll assume that you’ve already incorporated news stories into your app (for example, using an RSS feed). We’re going to use the stories that your users read as the signals of their interests, to recommend the next stories they’ll want to read.

Let’s further assume that the user of your app, selected this story about Syria and Russia.

With a single call to Primal, you can identify the user, their interest (the news story above), and the kind of content you want to recommend to them.

GET https://api.primal.com/v2/recommendations?uid=user1234&u=http://www.reuters.com/article/us-mideast-crisis-syria-idUSKCN11Z1IY&type=NewsArticle,VideoObject&sort=date

Let’s deconstruct this call:

  • /recommendations identifies the resource, generating recommendations for the user.
  • ?uid={user-identifer} identifies the user, using an identifier of your choosing.
  • u={URL} identifies the user’s current interest, in this case a link to a news article.
  • type={media-types} identifies the type of content you want to use, in this case news articles and videos.
  • sort={sorting-basis} specifies how you want the results sorted, in this by date.

Primal’s response to this request includes all the information you need to present the recommended content items in your app, such as the title, a short summary (abstract), and a thumbnail image.

Each content item also includes what we call a learning link. Here’s an example generated from the request above:

"url": "https://www.primal.com/syria/response/syrian/offensive;officials;operating;airstrike;damascus;vomiting;fighting;capital;moscow;russia;aleppo;rebels;forces;bashar;group;talks;hama;jund;plan?u=https%3A%2F%2Fwww.washingtonpost.com%2Fworld%2Fmiddle_east%2Fun-fighting-displaces-100000-in-central-syria-in-8-days%2F2016%2F09%2F07%2F46e17872-74d6-11e6-9781-49e591781754_story.html&r=https%3A%2F%2Fwww.washingtonpost.com%2Fworld%2Fmiddle_east%2Fun-fighting-displaces-100000-in-central-syria-in-8-days%2F2016%2F09%2F07%2F46e17872-74d6-11e6-9781-49e591781754_story.html"

Through these learning links, users are redirected quickly through our servers before they’re sent to the recommended content item. This redirect allows us to learn from each interaction with the content to deliver increasingly personalized and refined recommendations over time.

Finally, we’ll use our evolving profile of the user’s interests to recommend new content for them.

GET https://api.primal.com/v2/recommendations?uid=user1234&type=NewsArticle,VideoObject&sort=date

Note that the request is very similar to the request presented above, except that we didn’t include any reference to a specific object of interest such as a URL. Instead, Primal generated the description of their interests for this call based on their past interactions.

Learn More

Primal was designed with simplicity in mind, but there’s a tremendous depth of features in our product, as well. For more details on our API, please see our interactive documentation.

Support

If you’d like to connect with our team to discuss your use case or any questions you may have, see our Support section for how to reach us.