Skip to content

Migration Guide for AP WebFeeds Users

Use this guide if you are accessing AP WebFeeds directly and are migrating to AP Media API. If you are migrating from AP WebFeeds Manager and Agent to AP Media Agent and Portal, see AP Media Agent and Portal FAQs.

Highlights

  • Content. AP Media API provides access not only to three days, but up to 30 days' worth of content for the same media types as AP WebFeeds, including pictures, print graphics, video, audio and text/story with linked media (for example, pictures and/or video associated with text stories).

  • Workflow. AP Media API supports typical workflows and major functionality available today via AP WebFeeds:

    • Retrieving your plan details, such as product IDs for content available to you.
    • Getting a feed of content matching those product IDs at regular intervals and downloading content.
  • Global search for all media types. AP Media API allows you to search for content of any media type (text, photo, graphic, video and/or audio) in the same API request.

  • Content updates. AP Media API streamlines receiving content updates (feed sequencing in AP WebFeeds) by returning the next request link in the feed response.

    In AP Media API, you can receive all available content without missing any by simply following the next request link instead of constructing it using parameter values from the previous feed requests, as required by AP WebFeeds.

  • Formats. AP Media API responses are in JSON format, with text stories available in ANPA or NITF formats (IPTC 7901 and hNews formats are not available). For media types other than text, AP Media API supports the same formats for content file downloads as AP WebFeeds.

  • Metadata. You can control which metadata fields are returned in the feed response using the include and/or exclude parameters (see Customizing Response Fields).

  • Simpler structure of AP Top Headlines. Instead of 11 consecutive feed entries typically delivered by AP WebFeeds per AP Top Headline collection, AP Media API delivers only one feed entry with links to individual Top Headline stories (see AP Top Headlines).

  • Linked media with metadata. Metadata is now available for linked media (for example, for pictures and/or video linked to a story by AP editors). For easier processing, links to curated media and metadata are available directly from the feed response, not from NITF-formatted stories.

  • Duplicate detection. AP Media API makes it easy to avoid downloading duplicate linked content (for example, a curated picture linked to several stories) by using ETags (see Managing Revisions and Duplicates).

  • Inline links. AP WebFeeds provides inline links in NITF stories as an option. AP Media API always returns inline links in NITF, if available.

Typical Workflow

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. View example >>
  2. Get a feed of content for the product IDs. Make an initial request for a feed of content matching the retrieved product IDs (optionally, including all available content item metadata in the response). View example >>

    The feed response includes:

    • Content item metadata and download links.
    • The link to use in the next request.
  3. Process metadata and download content. Process returned content metadata and follow the links in the feed to download content files from the API. View example >>

    Once the content is saved to your CMS, it can be displayed by your news delivery application on your website or published through your other distribution channels, such as print and broadcast.

  4. Receive content updates. Use the link returned in the initial feed to make the next request. View example >>

    The response includes:

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

    You can now repeat this step to get updates.

Sample Calls for Typical Workflow

Retrieve Product IDs

Retrieve product IDs for the content available to your account.

AP WebFeeds

Note

WebFeeds uses HTTP Basic Authentication to authenticate all requests.

http://syndication.ap.org/AP.Distro.Feed/GetAccountInfo.aspx

AP Media API

Note

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

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

For more information, see Account Plans.

Get Feed for Product IDs

Get a feed of content from the last three days that matches either of the specified product IDs, along with all available content item metadata.

AP WebFeeds

http://syndication.ap.org/AP.Distro.Feed/GetFeed.aspx?idList=30029,31536&idListType=products

AP Media API

https://api.ap.org/media/v/content/feed?q=productid:(30079+OR+31536)+AND+mindate:>now-3d&include=*&apikey={apikey}

Notes

  • The +AND+mindate:>now-3d part of the query is optional and limits the content to the last three days, as delivered by AP WebFeeds. Removing this part from the query expands the timeframe to up to 30 days.
  • The optional include=* parameter is used to request all available content item metadata fields (a predefined set of fields is returned by default).

For more information about:

Download Content

Process the content metadata to identify renditions and download content files by following the links in the feed response.

AP WebFeeds

This example shows links to a story in ANPA and NITF formats.

<entry xmlns="http://www.w3.org/2005/Atom">
  <id>urn:publicid:ap.org:6dd764eabc914e6cbfb33e5319bf86d5</id> 
  <title>US--California Wildfires</title> 
   ... 
  <content type="text/plain" xml:lang="en-US">California wildfires reduce dreams to embers as flames grow</content> 
   ...
    <link rel="enclosure" title="AP Article" href="http://syndication.ap.org/AP.Distro.ContentBroker2/ContentBroker.aspx?contentid=2bf1fd3d5c814b63ab72fa8dce25b57a" length="4425" type="application/octet-stream">
      <apcm:Characteristics... FileExtension="anpa" Format="ANPA1312" MediaType="Binary" MimeType="application/octet-stream" Role="Main" SizeInBytes="4425" Words="738".../> 
    </link>
    <link rel="enclosure" title="AP Article" href="http://syndication.ap.org/AP.Distro.ContentBroker2/ContentBroker.aspx?contentid=2bf1fd3d5c814b63ab72fa8dce25b57a" length="4425" type="text/xml">
      <apcm:Characteristics... FileExtension="xml" Format="IIM" MediaType="Text" MimeType="text/xml" Role="Main" SizeInBytes="4425" Words="738".../> 
      ...
 </entry>

In AP WebFeeds, references to linked media (such as pictures and video associated with the story) are not available from the feed and are delivered only in the NITF-formatted story (see References to Linked Media in NITF returned by WebFeeds)

AP Media API

Tip

Item rendition download links cannot be constructed manually because they contain tokens that specify the rendition type, format and additional details required to download each rendition. Use item rendition download links available in the feed response.

This example shows a link to a story in NITF and ANPA formats in the API feed response ("renditions.nitf.href" and "renditions.anpa.href" respectively).

This story has a linked picture, which is available for download in "associations" in the feed response (not from the NITF rendition of the story as in AP WebFeeds (see References to Linked Media Media in NITF Returned by WebFeeds):

"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",
        "rel": "Story",
        "format": "IIM",
        "mimetype": "text/xml",
        "fileextension": "xml",
        "words": 708,
        "contentid": "7f30420307c7447ba7c9e39bebfa0d8d",
        "href": "https://api.ap.org/media/v/content/398ff826d5f0418a97b279b166cffc92/download?type=text&format=NITF"
      },
      "anpa": {
        "title": "Anpa Story Download",
        "rel": "Main",
        "format": "ANPA1312",
        "mimetype": "application/octet-stream",
        "fileextension": "anpa",
        "words": 708,
        "contentid": "7f30420307c7447ba7c9e39bebfa0d8d",
        "href": "https://api.ap.org/media/v/content/398ff826d5f0418a97b279b166cffc92/download?type=text&format=ANPA"
      }
   }
}

For more information, see Item Rendition Download and Content Metadata Fields.

References to Linked Media in NITF Returned by AP WebFeeds

Note

In AP Media API, references to linked media are available in "associations" in the feed response. NITF stories returned by AP Media API do not contain references to linked media.

In AP WebFeeds, references to linked media (such as pictures and video associated with the story) are available in the <media> section of an NITF document. This example shows a reference to the Main rendition of the linked picture.

<nitf version="-//IPTC//DTD NITF 3.4//EN" change.date="October 18, 2006" change.time="19:30">
 ...
  <body>
    <body.head>
      <hedline>
        <hl1 id="headline">California wildfires reduce dreams to embers as flames grow</hl1> 
         ... 
      </hedline>
       ...
    </body.head>
    <body.content>
       <media id="media:ebeecfbe978f4ce5b0e9fc845dea4714" media-type="Photo">
         ...
         <media-metadata id="media-metadata-Role:fb5bd7517df84f99a92cbe5a747998d5" name="Role" value="Main" />
         ...
         <media-reference id="media-reference:fb5bd7517df84f99a92cbe5a747998d5" mime-type="image/jpeg" name="AP Photo" source="http://syndication.ap.org/AP.Distro.ContentBroker2/ContentBroker.aspx?contentid=fb5bd7517df84f99a92cbe5a747998d5" alternate-text="Gina and Luke Baier" height="3347" width="5184" coding="jpg" /> 
         <media-caption id="media-caption:ebeecfbe978f4ce5b0e9fc845dea4714">
           <p>Luke Baier, left, and his wife Gina Baier look through the remains of their home in the Coffey Park area of Santa Rosa, Calif., on Tuesday, Oct. 10, 2017... (AP Photo/Ben Margot)</p> 
         </media-caption>
      </media>
      <block id="Main">
        <p>SANTA ROSA, Calif. (AP) - Jose Garnica worked for more than two decades to build up his dream home that was reduced to ashes in a matter of minutes by the deadly firestorm striking California's wine country.</p>
         ...
      </block>
    </body.content>
   <body.end /> 
  </body>
</nitf>

In AP WebFeeds, inline links to external websites related to the story content are returned in the body text of the NITF-formatted story when showInlineLinks=true is specified in a feed request. AP Media API always returns inline links in NITF, if available. This example shows an inline link to a YouTube video in the NITF story body.

<nitf version="-//IPTC//DTD NITF 3.4//EN" change.date="October 18, 2006" change.time="19:30">
  ...
  <body>
    ...
    <body.content>
      <block id="Main">
        <p>BARCELONA, Spain (AP) - The rallying cry erupted, almost precisely, after 17 minutes and 14 seconds of soccer in the match between Barcelona and Malaga.</p>
        <p>
          <a href="https://www.youtube.com/watch?v=vMCg84QWNhs">"In! In-de! In-de-pen-den-ci-a!"</a> 
        </p>
        <p>It rolled around and around the Camp Nou stadium like a tide, from behind one of the goals into a frothing chorus of thousands of voices.</p>
          ...
      </block></body.content></body><nitf> 

Receive Content Updates

Receive all content updated since your previous feed request.

AP WebFeeds

This example shows a feed request constructed based on the minDateTime and sequenceNumber parameter values from the previous feed response in conjunction with thesortOrder=chronological parameter.

http://syndication.ap.org/AP.Distro.Feed/GetFeed.aspx?idList=30029&idListType=products&minDateTime=2017-03-03T16:48:58.437Z&sequenceNumber=3914494&sortOrder=chronological

AP Media API

Tip

It is strongly recommended to receive content updates using the returned link to make the next request to ensure that you get all available content without missing any.

This example shows the next request link returned in the "next_page" property in the feed response:

  "data": {
    "query": "productid:30029",
    "updated": "2017-10-12T19:06:44.330Z",
    "current_item_count": 10,
    "next_page": "https://api.ap.org/media/v/content/feed",
    ...

For more information, see Getting Content Updates Using Next Request Links.

For Content Providers Submitting ATOM Feeds

If you submit content to AP via an ATOM feed that meets AP specifications, your IDs are delivered in foreignkeys; for example:

{// Example:
 "foreignkeys": {
   "memberentryid": "urn:publicid:localnewspaper.com:a1234b5678",
   "membermanagementid": "urn:publicid:localnewspaper.com:c9012d3456"}}

Other news management values that you submitted in the ATOM feed are returned in the AP Media API JSON properties mapped to the respective AP WebFeeds AP ATOM elements; for example, apnm:PublishingSpecialInstructions are returned in ednote.

For more information about the mapping of AP Media API metadata fields to AP WebFeeds fields, see Metadata Mapping.