How does the Gravity API for Publishers work?



  1. Register your site with a Gravity account manager
  2. Place your Gravity beacon in your page footer
  3. Provide RSS feeds for content ingestion
  4. Receive your API placement ID from your Account Manager

Keep in Mind

  • API implementations must be validated for correctness. Please contact your account manager to schedule a trial run before going live.
  • This endpoint is only supported via client-side requests due to caching limitations. Please contact your Account Manager if a server-side request is mandatory.
  • Be sure to implement the "impression viewed callback" as described below.
  • Links to recommended articles should use the rel=nofollow attribute.



This is Gravity’s core recommendation API. It returns a set of personalized stories for the user indicated by the userGuid parameter. Personalized stories are determined by the similarity between the user’s interest graph and the interest graph of available stories from the content source (usually the website using the API).


A 4 digit number representing the placement configuration. Provided by your Gravity Account Manager.

Example Value: 1234


The 32 character hexadecimal GUID of the user for whom to return the results. This value is stored by Gravity's beacon code in your site's cookie under the name "grvinsights". If the beacon code has not yet been stored, you may send the empty string once per user.

Warning: Be sure to send the userguid when it is available, or else personalization will not occur.

Example Value: 85cca408336572e970f89951ad7ea11c


Results will not include this URL and impressions for the API call are logged against this particular URL for reporting purposes.

Example Value:


The page of results to return. Results from previous pages will not be returned. The page count starts at "0" which is the default value if no page parameter is present. Subsequent pages can be retrieved by incrementing the page parameter. This parameter can be used to implement an "infinite scroll" feature where a user is continually shown new recommendations as they scroll down.

Example Value: 0


Specify the width of an image to return in the results if an image is available. There are 5 valid image sizes: 100, 200, 300, 400 or the original size. If a mid-range value is provided such as 150 the next largest size will be returned, in the case of 150 that would be 200. To return the original size, omit this parameter.

Example Value: 400

Our sample JS code can serve as a template:

Impression Viewed

The Impression Viewed Callback is a unique URL returned for each set of API results. The callback should be used to tell Gravity when a user has actually seen the recommendations being returned. When the user scrolls the rendered recommendations into view, please issue a request to the url returned as impressionViewed.callback. This is separate from the regular impression that is logged via a beacon on page load regardless of if the user saw the recommendations or not. By using the Impression Viewed Callback, Gravity algorithms can do further performance optimization and metrics such as optimizing based on impressions viewed.

Example Request
Example Response
        "title":"The World's Most Powerful Female Entrepreneurs of 2014",
        "summary":"From fresh faces to billionaires, entrepreneurs make up 20% of this year’s Most Powerful Women list. Their impact reaches business, media and philanthropy, and over the last year, many have leveraged their top-tier status for the greater good of social causes. These Power Women are setting an stron",
        "title":"Tesla's Clever Patent Move Is Already Paying Off",
        "summary":"Tesla may already be reaping the rewards of freeing up its patents. Four days after CEO Elon Musk offered most of his company’s patents to rivals in hopes of cultivating a bigger electric car market, Nissan and BMW are “keen on talks” to cooperate on charging networks, the Financial Times reported ",
        "author":"Alexander C. Kaufman",
    "executionTime":"658 milliseconds",
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request


Powered by Zendesk