Skip to content
Back to Home

Welcome to AP Media API

If you are looking for Developer documentation, you are in the right place. If you are migrating from AP WebFeeds Manager and Agent, see AP Media Agent and Portal FAQs.

For the first time, you can access all your licensed multimedia content programmatically through a simple API interface.

  • Perform granular searches across archives of all media types or receive a continuous feed of news content. To learn more, see Search or Feed?
  • Media types include text/story with linked curated content, pictures, print graphics, video and audio.
  • 30 days of content is available, as well as the full library of current and archive audio and print graphics content. Access will subsequently be expanded to include AP image and video archives.
  • Content item pricing based on your contract is returned for searches (typically not applicable to feeds).

Note

AP Media API supports the same content as AP Newsroom and AP WebFeeds, including content available via AP Content API and AP Breaking News API; depending on your contract terms. Please refer to contract information for details and contact your AP Sales or Licensing representative with any questions.

Search or Feed?

Choosing Search or Feed depends on how you plan to receive content:

  • Search is used to query a database of existing content to find what you are interested in; for example, all media related to an event that occurred last week. To learn more, see Typical Search Workflow and Search Examples.
  • Feed is used for content ingestion - monitoring a stream of content to receive all updates and new content going forward; for example, breaking news about wildfires. To learn more, see Typical Feed Workflow, Standard or Query Based Feed? and Feed Examples.

    Notes

    • 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. Learn more >>
    • AP Media API distinguishes between two types of feeds - standard and query based. Learn more >>
    • Pricing is typically not applicable to feeds.

Typical Search Workflow

If you are migrating from AP Content API or AP Breaking News API, see AP Content API Migration Guide or AP Breaking News API Migration Guide for typical workflows and examples.

Content API Typical Workflow

Work with your own editorial system. Your editors search and download content using your own editorial tools:

  1. Run a search. When an editor performs a search in your editorial system, your custom program searches the content available via AP Media API and displays search results along with key metadata and content item pricing. More about Search >>
  2. Pick a result to view metadata. When an editor selects a search result, your custom program retrieves full content metadata with pricing (if applicable) from the AP Media API system. More about Item Metadata >>
  3. Download content. When an editor wants to download a content file, your custom program downloads the requested file from the AP Media API system. More about Item Downloads >>
  4. Review your account information. When an editor wants to check how many downloads available for your plan have already been used or download your order history, your custom program retrieves your plan and usage information or order history from AP Media API. More about Account >>

Search Examples

Tips

  • To try these examples, replace {apikey} with your API key.
  • To learn more about request syntax and parameters, see Search.

How to find content from a specific calendar day?

This search returns content for various media types; for example, text stories, pictures and video:

https://api.ap.org/media/v/content/search?q=versioncreated:2018-01-19&apikey={apikey}

How to find text stories containing "Super Bowl" in the headline?

https://api.ap.org/media/v/content/search?q=headline:"Super+Bowl"+AND+type:text&apikey={apikey}

How to search for pictures of Emma Stone or stories about Ryan Gosling?

https://api.ap.org/media/v/content/search?q=(type:picture+AND+"Emma+Stone")+OR+(type:text+AND+"Ryan+Gosling")&apikey={apikey}

How to find text and video from a custom date range?

https://api.ap.org/media/v/content/search?q=type:(text+OR+video)+AND+versioncreated:[2017-01-19+TO+2018-01-22]&apikey={apikey}

How to find audio from the past two days?

https://api.ap.org/media/v/content/search?q=type:audio+AND+versioncreated:>now-2d&apikey={apikey}

How to search for the newest stories about technology?

https://api.ap.org/media/v/content/search?q=type:text+AND+subject:Technology&sort=versioncreated:desc&apikey={apikey}

How to search for AP-sourced pictures about an event on a specific day?

https://api.ap.org/media/v/content/search?q=type:picture+AND+event:olympics+AND+firstcreated:2014-02-17+AND+source:AP&apikey={apikey}

How to search using multiple categories?

This search returns stories for either f, i or n categories:

https://api.ap.org/media/v/content/search?q=type:text+AND+category:(f+OR+i+OR+n)&apikey={apikey}

How to find content about hurricanes in the Gulf of Mexico, but not in Puerto Rico?

Note that in this search, the optional include=* parameter returns all available metadata including subject and geography classifications:

https://api.ap.org/media/v/content/search?q=subject:hurricanes+AND+geography:("Gulf+of+Mexico"+AND+NOT+"Puerto+Rico")&apikey={apikey}&include=*

How to get video content with pricing?

AP Media API always returns price tags required for charge acknowledgment on priced downloads. To receive additional pricing information (for example, formatted item price, use code and pricing message), use the pricing=true parameter:

https://api.ap.org/media/v/content/search?q=type:video&pricing=true&apikey={apikey}

To learn more, see Pricing.

Typical Feed Workflow

If you are migrating from AP WebFeeds, see AP WebFeeds Migration Guide for a typical workflow and examples.

Pricing is typically not applicable to feeds.

API Typical Feed Workflow

  1. Retrieve product IDs for your account (typically done once). To get product IDs for content available to your account, retrieve your plan information from the API and save it to your CMS. More about Account Plans >>

  2. Get a feed of content for the product IDs. Make an initial request for a feed of content matching the specified criteria (for example, retrieved product IDs and/or keywords), optionally including all or specific content metadata in the response. More about Feed >>

    The feed response includes:

    • Content item metadata and download links.
    • The link to use in the next request.
  3. View content metadata. Retrieve full content metadata from the API. This step is optional if you requested to include all metadata of interest in the feed response. More about Item Metadata >>

  4. Process metadata and download content. Process content item metadata and follow the links in the feed to download content files from the API. More about Item Downloads >>

  5. Receive content updates. Use the link returned in the initial feed to make the next request.

    The response includes:

    • All content updated since your previous request.
    • The link to use in the next request.

    Repeat this step to get updates. More about Next Request Links >>

Standard or Query Based Feed?

AP Media API distinguishes between two types of feeds - standard and query based.

Standard Feed

A standard feed returns results on the initial request and may start anywhere in the past 72 hours. The standard feed request may specify zero or more product IDs and/or the mindate parameter; for example:

  • A specific product ID: /feed?q=productid:30079
  • A list of product IDs (separated by OR): /feed?q=productid:(30079+OR+31536)
  • All entitled content: /feed
  • Any of the above in conjunction with the mindate parameter to get a feed starting from a specific point in time during the past 72 hours; for example:

    • All entitled content starting from three days ago:

      /feed?q=mindate:>now-3d

    • A single product ID starting from one day ago:

      /feed?q=productid:30079+AND+mindate:>now-1d

    • Multiple product IDs starting from two days ago:

      /feed?q=productid:(30079+OR+31536)+AND+mindate:>now-2d

Query Based Feed

A query based feed refers to all of the other possible feed requests; for example:

/feed?q=soccer or /feed?q=productid:(30079+AND+31536)

A query based feed returns content published only after the time of the initial request and typically returns zero results on the initial request.

Following the next request link returns content that was published since the time of the initial request of this keyword feed. For example, if you follow the next page link 30 seconds after your initial request, you will get the items matching your query that have been published in the last 30 seconds.

Tips

  • Use Search to query for past content, even if that content was published a few minutes ago.
  • Before setting up a query based feed, check out the results of your query using Search and then follow the next request link on the last page of the search results to convert your search into a feed.

Feed Examples

Tips

  • To try these examples, replace {apikey} with your API key.
  • To learn more about request syntax and parameters, see Feed.

How to get breaking news about wildfires?

https://api.ap.org/media/v/content/feed?q=wildfires&apikey={apikey}

This feed request will return the newest items matching your query. To receive content updates, make the next request using the next_page link returned in the feed response. More about Next Request Links >>

How to get a feed for all entitled content?

https://api.ap.org/media/v/content/feed?apikey={apikey}

How to get a feed for a specific product ID?

https://api.ap.org/media/v/content/feed?q=productid:31989&apikey={apikey}

Tip

Your API key might not have access to this product ID. To get product IDs for your API key, try https://api.ap.org/media/v/account/plans?apikey={apikey} and look for entitlements.id values in the response. To learn more, see Account Plans.

How to get a feed for multiple product IDs along with all available content metadata?

The optional include=* parameter is used to request all available content metadata fields (a predefined set of fields is returned by default):

https://api.ap.org/media/v/content/feed?q=productid:(30079+OR+31536)&include=*&apikey={apikey}

How to get a feed starting with content from three days ago?

https://api.ap.org/media/v/content/feed?q=mindate:>now-3d&apikey={apikey}

If you do not specify mindate, the initial feed request will return the newest items matching your query.

How to get a feed of content that matches a specific keyword?

https://api.ap.org/media/v/content/feed?q=soccer&apikey={apikey}

How to get a Followed Topic feed created in AP Newsroom?

https://api.ap.org/media/v/content/feed?q=followedtopicid:709523&apikey={apikey}

Where 709523 is the desired Followed Topic ID. You can obtain the Followed Topic ID from the ID column on AP Newsroom's Followed Topics management page. Make sure that a feed has been created for this Followed Topic in AP Newsroom. To learn more, see Followed Topic Delivery.

Pricing

Notes

  • Content item pricing is available for search and item metadata calls.
  • If you are requesting feeds and have an unlimited subscription plan, pricing is typically not applicable.
  • When a content item rendition download incurs a charge, AP Media API requires the charge acknowledgment on the download of the content item rendition. Learn more >>

Thumbnails and previews are included in all plans, and downloading them never incurs any further billing or charges.

Main renditions are billed based on the specifics of each content item that are determined by your AP contract details for that particular type of content. Please refer to contract information for details and contact your AP Sales or Licensing representative with any questions.

Important

As part of your contract, you may be entitled to see content that is browse-only. For these content items, the API will return the links to the preview and thumbnail renditions; however, the links to the main renditions will not be available. You may NOT use the preview or thumbnail renditions of this browse-only content.

About plans

Typical plans include:

  • Unlimited subscription. Allows downloading as many items as desired. See example >>
  • Metered plan. Allows a certain number of downloads per month. See example >>
  • A la carte plan. An indicated price is charged for each download. See example >>
  • Choice plan. Includes multiple tiers of content, with each content offering having a different price based on the tier to which they belong. See example >>
  • Limited duration subscription. Content up to a certain number of days is included in the plan, and an extra charge applies to older content. See example >>

To check the details of your plan:

https://api.ap.org/media/v/account/plans?apikey={apikey}

To learn more, see Account Plans.

Price tags and additional pricing information

The API always returns price tags on priced downloads of content item renditions. These price tags must be used for acknowledging pricing on rendition downloads.

Additional pricing information (for example, formatted item price, use code and pricing message) is available upon request.

To get additional pricing information for each content item:

Use pricing=true in the request; for example:

https://api.ap.org/media/v/content/search?pricing=true&apikey={apikey}

To learn more, see Item Price, Use Code and Pricing Message.

API Keys

An API key is the access key required for making API calls.

Access Modes

Depending on your permissions, you can access each of the available API versions in one or more of these modes: live, preview and sandbox.

You can use the same API key to access all of the modes that you are allowed to use. To view the API versions and modes that are available to your account, use the API versions method.

Live Mode

Live mode (typically, the default) offers a fully functional API for use of your entitled content in production systems. Downloads of main renditions are billed based on the specifics of each content item that are determined by your AP contract. Learn more about pricing >>

Preview Mode

Preview mode allows you to safely test your code on your initial integration with the AP Media API and each time a new API version is released to ensure that the new features and changes are properly handled by your client application. AP strongly recommends testing the initial integration and subsequent changes in the preview mode before they become available in your production systems.

  • Entitled content with publishing and distribution restrictions. You can access your entitled content in the preview mode; however, you may NOT publish or distribute any of this content.
  • Restricted downloads. Intended for testing, the preview mode provides restricted download access compared to the live mode. The main renditions of a content item (for example, high-resolution images) are not available for download in the preview mode. Instead, demo mains are downloaded when you follow the links to main renditions.
  • No billing. Downloads in the preview mode do not incur any charges.
  • Pricing experience available for testing. In the preview mode, you can test the pricing experience including download exceptions; for example, when a price has changed or when a meter has expired. Use the pricing=true parameter in a search, feed or item metadata request, and then add one of the following parameters to download links: &testprice=changed to simulate Download After a Price Change or &testprice=unavailable to simulate No Permission to Download.

Sandbox Mode

Sandbox mode allows you to try out the API before you sign a contract with the AP.

  • Demo content with publishing and distribution restrictions. You may NOT publish or distribute any of the demo content that you download in the sandbox mode.
  • Restricted downloads. The main renditions of a content item (for example, high-resolution images) are not available for download in the sandbox mode. Instead, demo mains are downloaded when you follow the links to main renditions.
  • No billing. Downloads in the sandbox mode do not incur any charges.

Supported Protocols

HTTPS 1.1 is supported for the API calls to api.ap.org.

API Explorer

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

Getting Help

For technical help, contact AP Customer Support.