Frequently Asked Questions

AP Media API FAQs
AP Media Agent FAQs
General FAQs

How can I determine what kind of content I will receive over a particular product or package ID?
What are the "class" tags I'm seeing in NITF?
What is an abstract/summary? How can I get it?
What are photo banners that I am receiving?

AP Media API FAQs

What is AP Media API?

AP Media API a new programmatic delivery platform where you can access all your licensed multimedia content through a simple API interface. You can receive a continuous feed of news content or perform granular searches across archives of all media types.

What is AP Media Agent?

AP Media Agent is a Java application for content ingestion that allows you to automatically download news content available through AP Media API feeds. You can configure and manage your content ingest agents on the configuration dashboard in AP Newsroom.

Should I use Feed or Search to ingest my content?

Most of our customers ingest their content using the Feed method. If you're 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.

You can use the Search method to search for individual content items from our existing database of content, including archive content (if allowed by your contract).

Does the AP Media API support B2C (Business-to-Consumer) syndication?

No, AP Media API is designed for B2B (Business-to-Business) integration with your content ingestion systems or CMSs. The content and feeds must not be published directly to your websites. Usage beyond the standard B2B profile may be subject to auditing.

Should I use AP Media Agent or write a program to make direct calls to the AP Media API?

Writing a custom program is recommended if you are looking for tighter integration of your content ingestion system or CMS with AP Media API. However, this requires software development resources to implement a solution for processing a feed or searching and downloading content.

Alternatively, you can use the AP Media Agent, an out-of-the box solution for automatic content downloads that offers a wide variety of configuration options to meet your needs and allows you to start downloading content right away.

How do I get my list of entitlements?

Use this API request (supply the API key in the x-api-key request header):

https://api.ap.org/media/v/account/plans?[&format=csv]

By default, JSON is returned. Optionally, you can receive your plan details in the CSV format by adding the format=csv parameter to your request (see Account Plans).

What is the basic syntax and parameters used to make search requests?

See Search Examples and Search.

What is the basic syntax and parameters used to make feed requests?

See Feed Examples and Feed.

How do I authenticate the AP Media API and Agent?

An API key is required for making AP Media API calls.

A username/password is required to log in to the AP Newsroom, and an API key is required to register the AP Media Agent with the configuration dashboard.

What format is the API response in?

The API responses are delivered in JSON. Content item metadata is also optionally available as XML in the NewsML-G2 format.

Is there somewhere I can build and test live API calls?

The Swagger-based API Explorer is available. The API Explorer is an interactive quick reference that lists the API methods and parameters and allows for testing live API calls and generating sample code. An API key is required for testing live API calls.

What media types are available in the AP Media API?

Media types include text (stories with linked curated content), pictures, graphics, video and audio in various sizes and renditions (see Content File Formats and Renditions).

What kinds of metadata are available in the AP Media API?

Content item metadata returned by AP Media API includes AP classification metadata, which is designed to help you get the most out of the content delivered by the AP. For more information, see Content Metadata Fields (for the descriptions of the returned metadata fields), Leveraging AP Metadata (for metadata benefits, solutions and use cases) and AP Classification Metadata (for the possible values of the AP classification metadata elements).

What is linked curated media?

See Linked Media.

How far back in time can I go in Search?

The AP Media API Search method provides programmatic access to 30 days of content, as well as the full library of current and archive picture, video, audio and graphics content; depending on your contract terms.

How far back in time can I go in Feed?

The AP Media API Feed method and the AP Media Agent allow downloading content up to the last 72 hours; depending on your contract terms.

How can I get a Followed Topic feed via AP Media API?

See Feed Delivery of Personal Followed Topics.

What is Long Polling?

See About Long Polling.

How many product IDs should I combine into a single request?

To minimize duplicate content and maintain optimal efficiency, we recommend combining all package/product IDs into a single request unless your workflow calls for querying specific products in separate batches. If you are querying by package ID, there is no need to query individual products within that package because by default, querying a package includes all products within the package.

How do I use the include/exclude parameters in my requests?

See Customizing Response Fields.

Why can't I remove certain fields from the JSON response using the exclude parameter?

See Required vs. Default Fields.

How can I exclude AP Top News Headline packages from my feed/search results?

Add +AND+NOT+profile:(extendedheadlinepackage+OR+headlinepackage) to the value of your query parameter; for example:

https://api.ap.org/media/v/content/search?q=soccer+AND+NOT+profile:(extendedheadlinepackage+OR+headlinepackage)

How many items will be returned in my search/feed results?

The default is 10 items with a maximum of 100 per page. The page size can also be specified in the query using the page_size parameter (see optional parameters for Search and Feed).

How can I ensure that I'm only getting new content with each feed request?

To check for any updates since your previous request, use the "next_page" link returned in the feed response for the next request (see Getting Content Updates Using Next Page Links).

What if I just want the latest content?

If you only want to update the latest content, use the ETag returned in the feed response for the next request (see Getting the Latest Content Using Conditional Requests).

I am interested in specific video renditions. How can I ensure that I ingest them properly?

Each video delivered by AP Media API is made available in various renditions (formats, quality and encodings). To deliver new content to you as fast as possible, videos are released into AP Media API feeds as soon as some of the renditions are available and not necessarily when all renditions have finished being produced. As more renditions become available, the video content item will appear in your feed again with the same version and item ID (altids.itemid), but with more renditions available for download and a different ETag (altids.etag).

To avoid discarding video rendition updates as duplicates and therefore missing some of the renditions that you may be interested in (for example, MP4), make sure to use ETag rather than version to manage revisions and duplicates. For more information, see Managing Revisions and Duplicates.

How can I download metered or priced (non-subscription) content using the API?

When a content item rendition download incurs a charge, AP Media API requires the charge acknowledgment on the download of the content item rendition. See Acknowledging Pricing on Rendition Downloads.

How can I find a specific piece of content using the API?

Use the item ID of the content item in the Item Metadata request; for example:

https://api.ap.org/media/v/content/fedf6ff0f6564fc29449f189d9242349

How can I go to a specific point in time (within the last 72 hours) in a feed?

See Resetting Ingestion Time.

What are the possible error messages I could receive in the AP Media API?

See API Codes.

What are the throttle/quota limits for an API key?

Throttle/quota limits specify the maximum number of API calls allowed during a certain interval; for example, per minute or per day. These limits are used to manage the API's system capacity and the access rights of the API. AP Media API allows you to look up the throttle quota limits for an API key (see Account Quotas).

Where can I find API troubleshooting information?

See Troubleshooting.

AP Media Agent FAQs

See the AP Media Agent Quick Reference FAQs.

General FAQs

How can I determine what kind of content I will receive over a particular product or package ID?

Go to AP Newsroom, log in with your AP Newsroom credentials, enter productid:{productID} in the Search box, and you will see what content moved on this product ID in the last 30 days.

What are the "class" tags I'm seeing in NITF?

Some NITF content may contain HTML "class" attributes to help you with formatting this content using CSS if you wish.

What is an abstract/summary? How can I get it?

Note
Abstract (story summary) is an optional add-on to existing text services to which your organization may or may not be entitled. If you are interested in receiving this story element, please contact your AP sales representative.

The Abstract provides a summary of text stories written by AP journalists, which encapsulates the story in about 100 words. These summaries are great for digital and mobile use, social media properties, text-to-audio applications, and more.

If included in your service, the story summary is delivered in the "description_summary" field in the JSON search or feed response and in the <abstract> field in NITF stories.

{// Example:

"description_summary": "U.S. industrial production jumped a solid 0.9 percent in October. Factory activity recovered from the previous months' shuttering of assembly lines by Hurricanes Harvey and Irma. The Federal Reserve says that manufacturing activity surged 1.3 percent last month. Many of the gains came from a sharp increase in the production of chemical and petroleum and coal products. Motor vehicles and metals also posted decent gains."}

- <nitf version="-//IPTC//DTD NITF 3.4//EN" change.date="October 18, 2006" change.time="19:30">

   + <head>
   - <body>
     - <body.head>...
        + <dateline>
          <abstract>U.S. industrial production jumped a solid 0.9 percent in October. Factory activity recovered from the previous months' shuttering of assembly lines by Hurricanes Harvey and Irma. The Federal Reserve says that manufacturing activity surged 1.3 percent last month. Many of the gains came from a sharp increase in the production of chemical and petroleum and coal products. Motor vehicles and metals also posted decent gains.</abstract>
       </body.head>...

AP Media API and Media Agent always deliver all the story elements (story body, summary and headline) to which you are entitled in the same NITF file.

For example, you are using the Media Agent or making a Media API feed request for one or both or these product IDs:

Product ID 100135 Broadcast – APTV – Michigan (you are entitled to headline, extended headline, body)
Product ID 47066 Broadcast – Summaries – Michigan (you are entitled to headline and summary)

You will receive ALL the story elements to which you are entitled in the same NITF file: the summary in the <abstract>, the body in <body.content> and the headline in body.head/hedline/hl1.

Note
The extended headline is not part of NITF; it is available only in the "headline_extended" property in the Media API response.

What are photo banners that I am receiving?

See Picture Notification Banners.