Migration Guide for AP WebFeeds Users

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 page link in the feed response.

  In AP Media API, you can receive all available content without missing any by simply following the next page 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. Content item metadata is also optionally available as XML in the NewsML-G2 format. Text stories are delivered in the NITF format. ANPA, IPTC 7901 and hNews formats are not available. If you are currently using ANPA, see the ANPA Migration Metadata Guide for more information about metadata fields that you can use to route and manage content. 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.

• Abstract/summary. (If you are entitled to abstract/summary) The story elements (story body, summary and headlines) returned in the NITF file by AP WebFeeds or WebFeeds Agent depend on whether you are requesting content for one product ID at a time or combining those product IDs in the same request. AP Media API and Media Agent always deliver all the story elements to which you are entitled in the same NITF file. See example >>

Typical 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

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

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

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

All subsequent feed requests must use the next_page link from the previous feed response (see Getting Content Updates below).

For more information about:

• Feed requests in AP Media API, see Feed.

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

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

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 the NITF format.

<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="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

This example shows a link to a story in the NITF format in the API feed response ("renditions.nitf.href"). 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"}}}

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

References to Linked Media in NITF Returned by AP WebFeeds

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>

Inline Links in 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>

Abstract/Summary in NITF

If you are entitled to abstract/summary, the story elements (story body, summary and headlines) returned in the NITF file by AP WebFeeds or WebFeeds Agent depend on whether you are requesting content for one product ID at a time or combining those product IDs in the same request. AP Media API and Media Agent always deliver all the story elements to which you are entitled in the same NITF file.

If you are using a WebFeeds Agent or making a WebFeeds direct call for only ONE product ID

You will receive the story elements you are entitled to for that ONE product ID; for example:

• For product ID 100135 Broadcast – APTV – Michigan (you are entitled to headline, extended headline, body): the body in body.content and the headline in body.head/hedline/hl1 in NITF
  Note: The extended headline is not part of NITF; it is available only in the <apcm:ExtendedHeadLine> element in the feed.

• For product ID 47066 Broadcast – Summaries – Michigan (you are entitled to headline, summary), for the same story as above: the summary in both body.head/abstract and body.content, and the headline in body.head/hedline/hl1.

If you are making a WebFeeds direct call for BOTH 100135 and 47066 in the same request, using the Media Agent or making a Media API feed request for one or both or these product IDs

You will receive ALL the story elements to which you are entitled in the same NITF file: the summary in body.head/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 <apcm:ExtendedHeadLine> element in the feed returned by WebFeeds and in the "headline_extended" property in the Media API response.

Quick Reference: NITF abstract/summary delivery

*The extended headline is not part of NITF; it is available only in the <apcm:ExtendedHeadLine> element in the feed returned by WebFeeds and in the "headline_extended" property in the Media API response.

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 the sortOrder=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

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

{// Example:

  "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 Page 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.