Feed

 

ON THIS PAGE      Show

 

 

 

 

 

Most of our customers ingest their content using the Feed method. If you are not sure which method to use, we recommend starting with Feed.

The Feed method allows you to:

  • Receive a stream of new content as it is published by the AP.

  • Limit the number of duplicate items downloaded and ensure you are not missing any items.

 

 

 

Video Tutorial

Getting Content Updates Using Next Page Links (02:40)

Description

Returns a feed of content matching the specified criteria. The returned feed items are sorted in chronological order, with the newest items at the bottom of the feed.

Feeds are used for content ingestion - monitoring a stream of content to receive all updates and new content going forward. To learn more, see Typical Feed Workflow and Feed Examples in Getting Started.

About Long Polling

For efficiency on feed requests, the AP Media API server uses HTTP long polling where the server holds the client's feed request open until new content becomes available or up to 15 seconds. If there is new content when your client application makes the feed request, this content is immediately returned. Otherwise, the content is returned as soon as it becomes available during the next 15 seconds. An empty response is returned only if no new content is available after 15 seconds, which helps minimize the number of empty responses and improves efficiency.

 

  Tip

 

To receive your AP breaking news content in a timely manner and to ensure your feeds do not get behind, follow the next_page link as soon as it is returned in the feed. There is no need to wait any period of time between your polling requests.

 

 

 

Request

Required Request Header

  • x-api-key. Specifies the API key to authorize the request. The x-apikey header is also currently supported.

Optional Request Header

  • Accept-Encoding. Compresses the response to the gzip format. The valid value is gzip.

Request URI

  • Method: GET

  • Initial Feed Request URI (must be URL-encoded):

    https://api.ap.org/media/v[{version}]/content/feed?[{optional_parameters}]

 

 

  Important

 

 

To check for any updates since your previous feed request, you must either follow the "next_page" link from the feed response or use conditional GET requests, depending on your Feed workflow. For more information, see Best Practices for Using Feeds.

 

 

 

 

Base URI Parameter

  • version (optional). The API version; for example, 2.0. When this parameter value is not specified, the API version set as default for your account is returned.

For more information, see API Versions.

Optional Parameters

  • include, exclude. Parameters used to customize the fields returned in the response. For more information, see Customizing Response Fields.
  • page_size. The maximum number of items to return per page. The default is 10 items with a maximum of 100 per page.
  • pricing. Specifying pricing=true in the request returns complete pricing information for each content item, including formatted price, use code and pricing message in addition to the price tags on renditions, which are returned by default. To learn more, see Pricing.
  • in_my_plan. Specifying in_my_plan=true in the request returns only those items that do not incur any additional cost to download. Additionally, items returned include only those associations that do not incur any additional cost to download.
  • session_label. The tracking label to be applied to the session. The maximum number of characters in the label is 48, and only alphanumeric characters, periods, underscores and hyphens are allowed (a-z, A-Z, 0-9, . , _ and - ). For more information, see Labeling a Session Using a Request URL Parameter.

Request URI Examples

See Feed Examples in Getting Started and Supported Query Syntax.

Response

The Feed method returns the standard HTTP status code of "200 - OK" and a feed of content in the JSON format.

Each feed entry includes the content item ID, a requested set of metadata and links to all renditions of the content item (for example, thumbnail, preview and high-resolution versions of a picture).

For information about error codes, see API Codes.

Response Headers

  • x-mediaapi-Q-name. The API method to which the throttle/quota applies (corresponds to the "method" property returned by Account Quotas. Possible values are search, feed, account, download, ondemand, item, other.

  • x-mediaapi-Q-secondsLeft. The number of seconds remaining in the current period.

  • x-mediaapi-Q-used. Indicates the current usage and limit (the maximum number or calls allowed during the period), in the format {usage}/{limit}; for example, 1/6.

  • x-mediaapi-QDay-minutesLeft. (Optional; returned if a per-day quota is configured) The number of minutes remaining in the current period.

  • x-mediaapi-QDay-used. (Optional; returned if a per-day quota is configured) Indicates the current usage and limit (the maximum number or calls allowed during the period), in the format {usage}/{limit}; for example, 2/5000000.

Top-Level Properties

  • api_version. The API version.
  • api_mode. The API mode; for example, "live" or "preview."
  • api_build. The API build number.
  • id. The response ID.
  • method. The API method name and HTTP method.
  • org_name. Organization name.
  • session_label. A session tracking label applied either by adding the session_label={yourLabel} parameter to your request URL or by entering the Content Management System (CMS) name and version for your agent in the CMS Name and Version box on the Manage Ingest page of the Agent Dashboard. For more information, see Session Labels.
  • params. Parameters used in the API request.
  • data. Contains the data and metadata associated with the response.

Response Descriptive Properties

  • query. The q parameter value used in the API request.
  • updated. The date and time (in UTC) when the response was generated.
  • current_item_count. The number of items on the current page.

  • next_page. A link to the next page of the feed.

     

 

  Tip

 

 

To check for any updates since your previous request, it is strongly recommended that your client application use the "next_page" link returned in the feed response for the next request. For more information, see Using Next Page Links for Content Updates.

 

 

 

 

  • items. Contains all of the items on this page.

Item Descriptive Properties

  • meta. Contains the non-content specific metadata for an item.
    • products. Contains AP products or packages to which the content item belongs.
      • id. The product or package ID.
      • name. The product or package name.
    • followedtopics. Contains AP Newsroom Followed Topics to which the content item belongs.
      • id. The Followed Topic ID.
      • name. The Followed Topic name.
     

 

  Note

 

 

The "products" and "followedtopics" properties are not returned by default. Use the include parameter to include these properties in the response.

 

 

 

 

Sample Feed Response

This example shows a response to the following request (the API key is supplied in the x-api-key request header):

https://api.ap.org/media/v/content/feed?q=productid:31989&include=*

The include=* parameter is specified in this request to illustrate the "products" and "followedtopics" properties, which are not returned by default.

{
  "api_version": "2.0",
  "api_mode": "live",
  "api_build": "2.0.2", 
  "id": "r10Q829oZ",
  "method": "/content/feed.GET",
  "org_name": "My Organization",
  "params": {
    "include": [
      "*"
    ],
    "q": "prodictid:31989",
  },
  "data": {
    "query": "prodictid:31989",
    "updated": "2020-07-02T17:49:26.752Z",
    "page_size": 10,
    "current_item_count": 10,
    "next_page": "https://api.ap.org/media/v/content/feed?q=prodictid:31989&seq=217647413",
    "items": [
      {
        "meta": {
          "products": [
            {
              "id": 31989,
              "name": "AP Online Top General Headlines"
            }
          ],
          "followedtopics": [
            // AP Newsroom Followed Topics to which the content item belongs
          ]
        },
        "item": {
          // Human-readable usage terms, content metadata and download links
        }
      }
    ]
  }
}