ContentGems Developer Documentation

Developer documentation home

API documentation

Website widget documentation

ContentGems web app

API info page

Recommendations

This endpoint returns the top Recommendations for:

Make sure to review the API query documentation.

Recommendations for Interests

Resource URL

GET https://contentgems.com/api/v1/interests/<interest_id>/recommendations.json

Request Parameters

NameDescriptionOptional, required, defaults
interest_idThe id of the Interest.Required
max_itemsThe maximum number of Recommendations to return.Optional, default: 5
query_refinement A string to be appended to the query defined on the interest to further refine the recommendations. Example: On a "Restaurants" base query, you might want to add +"San Francisco" as a refinement. Please see the query documentation for syntax and operators. Also make sure to URL encode any special characters. The earlier example would look like this: GET https://contentgems.com/api/v1/interests/123/recommendations.json?query_refinement=%2B%22San%20Francisco%22 Optional, default: nil

Response Attributes

The response is an array of Recommendation objects. Each Recommendation has the following attributes:

NameDescription
excerptThe first 300 characters of the recommended article.
found_atThe date and time in UTC when ContentGems found the article.
host_nameThe host name of the URL.
imagesAn array of image urls.
popularity A measure of the recommended article's popularity on a scale of 0 to 100.
0 means not popular, 100 means extremely popular.
titleThe HTML document title of the recommended article, or the URL if no title is present.
urlThe URL of the recommended article.
videosAn array of video urls.
word_countThe number of words in the recommended article.

Example

Request:

GET https://contentgems.com/api/v1/interests/1433/recommendations.json

Response:

[
  {
    "excerpt": "Lorem ipsum ...",
    "found_at": "Fri Jul 21 13:58:46 +0000 2012",
    "host_name": "contentgems.com",
    "images": [
      { "url": "http://static.contentgems.com/image1.jpg" },
      { "url": "http://static.contentgems.com/image2.jpg" }
    ],
    "popularity": 42,
    "title": "Accelerate your content marketing",
    "url": "https://contentgems.com",
    "videos": [
      { "url": "http://static.contentgems.com/video1.mp4" },
      { "url": "http://static.contentgems.com/video2.mp4" }
    ],
    "word_count": 256
  },
  ...
]

Recommendations for ad-hoc queries

Resource URL

GET https://contentgems.com/api/v1/query/recommendations.json

If you have a lot of query params, then you can also use a POST request and submit the params in the request body to avoid length restrictions on URLs for GET requests.

Request Parameters

Name Description Optional, required, defaults
query The search query as string. Please see query documentation for details.
Query string example for the required phrase +"Content Marketing": query=%2B%22Content%20Marketing%22. Query string example for the two required fuzzy terms "+solar~0.3 +panels~0.3": query=%2Bsolar~0.3%20%2Bpanels~0.3
Required
dedup_similarity_threshold ContentGems removes duplicate articles from the recommendations. It computes the Jaccard index for each article pair in the result set and groups together any articles with very high Jaccard similarity indexes, only showing the most popular one. The `dedup_similarity_threshold` determines at what Jaccard index two articles are considered duplicates. Practical values are between 0.5 (vaguely similar article body text) and 0.99 (identical article body text). Optional, default: 0.85
domain_ids_to_exclude List of domain ids to exclude from recommendations. No URLs from any of the excluded domains will be included in recommendations.
Query string example: domain_ids_to_exclude[]=1&domain_ids_to_exclude[]=2. You can retrieve a Domain Name's domain_id using the Domains API endpoint. Note: You can also get a recommendation’s domain_id from a result in the web UI by hovering over the result‘s ‘Block Domain’ link and reading out the `i_source_id` parameter.
Optional, default: [] (empty array, no exclusions)
feed_bundle_ids_to_exclude List of Feed bundle ids to exclude from recommendations. No URLs from any of the excluded feed bundles will be included in recommendations.
Query string example: feed_bundle_ids_to_exclude[]=1&feed_bundle_ids_to_exclude[]=2. You can retrieve a Feed Bundle's id from the web UI: Go to "Manage Sources" / "Manage Bundles". Hover over the "Edit" link for the bundle you want and read out the number after the /i_feed_bundles/ segment in the URL.
Optional, default: [] (empty array, no exclusions)
feed_bundle_ids_to_use List of Feed bundle ids to limit recommendations to. Only URLs from the used feed bundles will be included in recommendations.
Query string example: feed_bundle_ids_to_use[]=1&feed_bundle_ids_to_use[]=2. You can retrieve a Feed Bundle's id from the web UI: Go to "Manage Sources" / "Manage Bundles". Hover over the "Edit" link for the bundle you want and read out the number after the /i_feed_bundles/ segment in the URL.
Optional, default: [] (empty array, no limitations)
found_within Recommendations must have been found within the given time period. One of 'last_24_hours' or 'last_7_days'.
Query string example: found_within=last_24_hours
Optional, default: 'last_24_hours'
max_items The maximum number of Recommendations to return.
Integer between 1 and 50.
Optional, default: 5
max_word_count Recommendations must have at most this many words.
Integer between 1 and 10,000.
Optional, default: Nil
minimum_popularity Recommendations must have a popularity equal to or higher than this.
One of:
"none", "very_low", "low", "medium", "high", or "very_high".
Optional, default: "none"
minimum_score Recommendations must have a score higher than this. Scores are computed by the indexed search engine and typically range from 0.01 to 15.
Query string example: minimum_score=0.5
Optional, default: Nil
min_word_count Recommendations’ body text must have at least this many words.
Integer between 1 and 10,000.
Optional, default: Nil
min_word_count_title Results’ title must have at least this many words.
Integer between 1 and 10,000.
Optional, default: Nil
must_have_image Recommendations must have images. Boolean true or false.
Query string example: must_have_image=true
Optional, default: false
must_have_video Recommendations must have videos. Boolean true or false.
Query string example: must_have_video=true
Optional, default: false
rank_by Recommendations will be ranked by this attribute before the top items are selected. One of 'relevancy' or 'popularity'.
Query string example: rank_by=popularity
Optional, default: 'popularity'
response_fields List of response fields to return. Array containing any of the following strings:
  • excerpt
  • found_at
  • host_name
  • images
  • popularity
  • score
  • title
  • url
  • videos
  • word_count
  • highlights
Query string example: response_fields[]=title&response_fields[]=url
Optional, default: all fields
sort_by Recommendations will be sorted by this attribute after the top items are selected. One of 'date', 'relevancy' or 'popularity'.
Query string example: sort_by=date
Optional, default: 'date'

Response Data

Contains all the fields documented under Interests, with the addition of the following:

NameDescription
score The score computed by the indexed search engine. It typically ranges from 0.01 to 15.
highlights Up to 3 document fragments that match the query, with matching terms highlighted. This is useful for debugging queries, as well as providing summarized context to readers.
Example highlights for the query string 'test':
{
  'highlights': [
    "Subject: <em>test</em> In a recent post, they report the results",
    "Rorschach <em>test</em> of U.S.-Turkish, with Ankara viewing them"
  ]
}

Example

Request:

GET https://contentgems.com/api/v1/query/recommendations.json?query=test%20query&response_fields[]=title&response_fields[]=url

Response:

Same as response data for Interests. Please see above for details.

API queries

Below is a list of ContentGems Recommendation API query examples. You need to URL encode each plain text query before submitting it to the ContentGems API.

Description Plain text query URL encoded query
Basic query: Article must contain "banana". +banana %2Bbanana
Phrases: Article must contain "banana boat". +"banana boat" %2B%22banana%20boat%22
Multiple terms: Article must contain "apple" and "banana". +banana +apple %2Bbanana%20%2Bapple
Should, must, must-not terms: Article should contain "apple" and/or "banana", must contain "lemon", and must not contain "pear". apple banana +lemon -pear apple%20banana%20%2Blemon%20-pear
Field specifiers: Article must contain "apple" in the title and "banana" in the excerpt. +title:apple +excerpt:banana %2Btitle%3Aapple%20%2Bexcerpt%3Abanana
Boolean OR: Article must contain "apple" or "banana" in the title. +title:(apple banana) %2Btitle%3A%28apple%20banana%29
Wildcards: Article must contain words that start with "banana", e.g., "banana" and "bananas". +banana* %2Bbanana%2A
Boosting: Prefer articles that contain "apple" over those that contain "banana" or "pear". apple^2 banana pear apple%5E2%20banana%20pear
Fuzzy matches: Match both "color" as well as "colour". ~color0.3 ~color0.3

Available fields

URL encoding

All your API queries must be URL encoded before you submit them to ContentGems. You can use an online URL encoder or use the table below for common characters:

Further information

Please see the ContentGems help documentation for more information on queries.