Migration Guide for AP Breaking News API Users

Highlights

• Content. Content available via AP Media API includes not only text as in AP Breaking News API, but also pictures, graphics, video and audio. AP Media API also delivers linked media (for example, pictures and/or video associated with news stories).

• Workflow. AP Media API supports a typical workflow and major functionality currently available in AP Breaking News API:

  • Retrieving your plan details, such as product IDs for content available to you ('content category list'  in AP Breaking News API).

  • Getting and downloading the latest content matching a product ID ('content by category'  in AP Breaking News API).

• Formats. AP Media API responses are in JSON format, with text stories available in NITF format.

Typical Workflow

1. Get product IDs for your account. To get product IDs ('categories' in AP Breaking News API) for content available to your account, retrieve your plan information from the API and save it to your CMS. View example >>

2. Search content by product ID. Search the API for the latest content matching each retrieved product ID. View example >>

3. Download content. Follow the links in the search results to download content files from the API. Once the files are saved to your CMS, your news delivery application displays the content. View example >>

Sample Calls for Typical Workflow

Get Product IDs

Retrieve product IDs ('categories'  in AP Breaking News API) for content available to your account.

AP Breaking News API

https://developerapi.ap.org/v2/categories.svc?apiKey={apiKey}

AP Media API

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

For more information, see Account Plans.

Search Content by Product ID

Search for the latest content matching a specific product ID.

AP Breaking News API

This example shows a request with the option to include linked pictures in the response if available (using the mediaOption=1 parameter shown as optional in square brackets [ ]). By default, returned content is sorted in reverse chronological order, with the latest at the top of the response.

https://developerapi.ap.org/v2/categories.svc/31995?apiKey={apiKey}[&mediaOption=1]

AP Media API

This example shows a request with the sort=versioncreated:desc parameter specified to receive content in reverse chronological order. Linked media (if available) is returned as "associations".

https://api.ap.org/media/v/content/search?apikey={apikey}&q=productid:31995&sort=versioncreated:desc

For more information about searching in AP Media API, see Search.

Download Content

Download content files from the API by following the links in search results.

AP Breaking News API

This example shows a link to a story in AP News Archive and a reference to a linked picture in the 'Content by Category' response.

<entry>

  <id>urn:uuid:1c680923644743a0a2dba42e5fe212e4</id> ...

  <link rel="alternate" type="text/html" href="http://www.apnewsarchive.com/2014/Butterball-says-fans-of-itsturkey-products-are-'Turketarian'/id-1c680923644743a0a2dba42e5fe212e4"/> ...

  <content type="xhtml">

    <div xmlns="http://www.w3.org/1999/xhtml">

      <div class="hnews hentry item">

        <div class="hmedia">

          <a rel="enclosure" type="image/jpeg" href="http://binaryapi.ap.org/3d0c1c602e3c471b8b6d80e8849453b3/preview.jpg">

            <img border="0" class="photo" alt="This image from video provided by Butterball shows a scene from one of two new TV ads the company is launching. Trying to get the word out that Butterball makes more than just the big bird on Thanksgiving Day, the company is launching the ads that showcase its range of products from turkey sausage to turkey burgers and focus on people who love the lean protein. (AP Photo/Butterball)" src="http://binaryapi.ap.org/3d0c1c602e3c471b8b6d80e8849453b3/thumbnail.jpg"/></a> ...

        </div> ...

      </div>

    </div>

  </content>

</entry>

AP Media API

This example shows a link to a story in NITF format in "renditions.nitf.href" in API search results. This story also has a linked picture, which is available for download in "associations".

{// Example:

"item": {

  "uri": "https://api.ap.org/media/v/content/398ff826d5f0418a97b279b166cffc92",

  "altids": {

    "itemid": "398ff826d5f0418a97b279b166cffc92", ... },

  "type": "text", ...

  "headline": "Uber wields new weapon in fight with London: diplomacy", ...

  "associations": {

    "1": {

      "uri": "https://api.ap.org/media/v/content/8e0cea16e82343e6899d3e733aeac2d0",

      "altids": {

        "itemid": "8e0cea16e82343e6899d3e733aeac2d0"},

      "type": "picture",

      "headline": "Britain Uber"}},

  "renditions": {

    "nitf": {

    "title": "NITF Story Download",

    "format": "IIM",

    "mimetype": "text/xml",

    "fileextension": "xml",

    "words": 182,

    "href": "https://api.ap.org/media/v/content/398ff826d5f0418a97b279b166cffc92/download?type=text&format=NITF"}}}

For more information about:

• Downloading content in AP Media API, see Item Rendition Download.

• Viewing full item metadata in AP Media API, see Content Item Metadata.

• AP Media API item metadata field descriptions, see Content Metadata Fields.

• Mapping of AP Media API metadata fields to AP Breaking News API fields, see Metadata Mapping.