AP CONTENT API 2.

8
Developers Guide

October 29, 2014

AP CONTENT API 2.8

TABLE OF CONTENTS
INTRODUCTION....................................................... 3

SEARCH .................................................................... 6

About This Guide ................................ 3

Audience ................................................... 3
Searching This Guide ............................... 3
Conventions.............................................. 3

Search Method .................................... 6

Description ............................................... 6
Request ..................................................... 6
Response................................................... 9

Related Documents and Resources .... 3

FAQs and Troubleshooting ...................... 3
Testing Live API Calls with API Console.. 3
Code Examples ......................................... 3

Supported Search Syntax .................. 19

Contacting Support............................. 3

CONTENT ITEM .................................................... 22

Item Metadata Method ...................... 22
Description ............................................. 22
Request ................................................... 22
Response................................................. 22

About AP Content API......................... 4

AP Images................................................. 4
AP Video-US ............................................. 4
Typical Workflow Overview ..................... 4
API Keys ................................................... 4
Supported Protocol .................................. 4
Client Implementation Requirement ....... 5
Recommended Practice............................ 5

APPENDIX ............................................................. 29

Whats New in This Release ................ 5

Error Codes ....................................... 29

Preview Environment ......................... 5

Top-Level Subject Categories ............30

October 29, 2014 | 2014 The Associated Press

Item Rendition Download Method.... 26

Description ............................................. 26
Request ................................................... 26
Response................................................. 28

AP CONTENT API 2.8

INTRODUCTION
ABOUT THIS GUIDE
Audience
This guide is intended for software engineers who develop applications that access AP Images and AP
Video-US content through application programming interfaces (APIs).

Searching This Guide

To search this guide, choose Edit Find in Adobe Acrobat.

Conventions

In request syntax, variable names are shown in braces { }. Optional parameters are shown in
brackets [ ]. Do not type the braces and brackets in the request.

In response descriptions, attributes are indicated by an at sign (@).

In response examples, an ellipsis () indicates information that is omitted for brevity.

RELATED DOCUMENTS AND RESOURCES

FAQs and Troubleshooting
AP Content API FAQs are available at http://customersupport.ap.org/api/Help/index.htm. They
provide an introduction to the API, reference all available documentation and resources, and offer
troubleshooting information for frequently encountered issues.

Testing Live API Calls with API Console

The API Console, an interactive quick reference that lists the API calls and parameters and allows for
testing live API calls is available at https://developer.ap.org/api-console.

Code Examples
To get started with AP Content API development, you can follow sample code (for example, in C#,
Java, PHP, Python and PowerShell) at https://github.com/TheAssociatedPress/APISamples.

CONTACTING SUPPORT
For technical help, contact AP Customer Support:

Phone: 877-836-9477 (U.S. toll-free number) or 212-621-7361 (from outside of the U.S.)

E-mail: [email protected]

Website: http://customersupport.ap.org

To comment on the documentation, send an e-mail message to [email protected].

October 29, 2014

AP CONTENT API 2.8

ABOUT AP CONTENT API

The AP Content API allows you to search and download content using your own editorial tools,
without having to visit AP portals, such as apimages.com.

AP Images
With millions of images dating back more than 100 years, AP Images is one of the worlds largest
collections of historical and contemporary imagery. The AP Images collection is constantly updated
and includes entertainment, fashion, news and sports coverage from The Associated Press and a
variety of content partners. The API provides access to AP-owned, member-owned and third-party
images, including the full AP Images archive and the GraphicsBank collection.

AP Video-US
AP Video-US offers U.S. broadcasters access to a daily selection of top news and features from the U.S.
and around the world. Videos cover regional, national, international, entertainment and investigative
news along with various lifestyle topics. The API provides access to videos from the last ten days.

Typical Workflow Overview

Work with your own editorial system. Your editors search and download AP Images or AP
Video-US content using your own editorial tools:
Run a search. When an editor performs a search in your editorial system, your custom
program searches the AP Images or AP Video-US collection and displays search results along
with key metadata.
Pick a particular result. When an editor selects a search result, your custom program
retrieves full content metadata from the AP Content API system.
Download an image or video. When an editor wants to download an image or video file,
your custom program downloads the requested content file from the AP Content API system.

API Keys
An API key is the access key required for making API calls. If you have not received your API key,
please contact Customer Support.

Supported Protocol
HTTPS 1.1 is supported for all API calls.

October 29, 2014

AP CONTENT API 2.8

Client Implementation Requirement

The implementation of your client application must allow new data elements and attributes to be
added by AP by ignoring any markup that it does not recognize.

Recommended Practice
It is recommended that your client application download content item renditions or retrieve full
metadata using the links returned in search results instead of constructing those links.
Note: This practice is also beneficial since the links returned in search results may contain
additional optional parameters used for performance or troubleshooting.

WHATS NEW IN THIS RELEASE

Resolved Issue (not applicable to GraphicsBank)
Search results now include the editorial priority of the content (the <category
scheme=http://cv.ap.org/urgency/> element in XML and the 'urgency' property in JSON).

Known Issue (not applicable to GraphicsBank)

Searches by transref (http://api.ap.org/v2/search/photo?transref=EPNY01&arrivalDate=2013-10-08) may
return no results. The arrivalDate parameter in the search request by transref erroneously searches
the content item's <published> date instead of its <updated> date. If the item's <updated> and
<published> dates are the same, the item is returned in search results; however, if these dates are
different, the item is not found by transref, and no results are returned.

PREVIEW ENVIRONMENT
The AP Content API preview environment allows you to test new features and changes prior to the
general release to ensure that they are properly handled by your client application. While these
upgrades do not require any modifications to your client application, AP strongly recommends testing
the changes in the preview environment before they become available in your production systems.

Preview Server URL: https://apipreview.ap.org.

Preview Key. A separate key is required for accessing the preview environment. To request the
preview key, please contact your AP Sales representative.

Restricted Downloads. Intended as a testing platform, the preview environment provides

restricted download access compared to the production environment. The main renditions of a
content item (for example, high-resolution images) are not available for download in the preview
environment.

October 29, 2014

AP CONTENT API 2.8

SEARCH
SEARCH METHOD
Description
Searches AP Images or AP Video-US content using the specified search criteria.

Request
METHOD

REQUEST URI

GET

https://api.ap.org/{version}/search[/{mediaType}]?apiKey={apiKey}[{Optional
SearchParameters}]

Important: The request URI must be URL-encoded.

Request URI Parameters

Required Base URI Parameter
PARAMETER

DESCRIPTION

VALID VALUE

version

The API version. Currently, the only valid value is v2.

v2

Optional Base URI Parameter

PARAMETER

DESCRIPTION

EXAMPLE

mediaType

The content media type. Valid values are:

photo (this is the default for AP Images, including all GraphicsBank content)
graphic
video

video

Optional Search Parameters

Note: An implied AND operator is used between the parameters.
PARAMETER

DESCRIPTION

EXAMPLE

The query expression. Parameters marked by a dagger () in

this table can also be used as part of the query expression along
with additional metadata fields. For more information, see
Supported Search Syntax on page 19.

Sarah+Jessica+
Parker
Tom+Cruise&creation
Date%3E2008

contentSet

The AP Images content set to be searched. Valid options are:

editorial: Editorial images.
creativeRM: Creative rights-managed images.
creativeRF: Creative royalty-free images.
GraphicsBank: All GraphicsBank content.
GraphicsBank_Graphic: Graphics content from GraphicsBank.
GraphicsBank_Photo: Photo content from GraphicsBank.
all: All available content sets (this is the default).

editorial
GraphicsBank

October 29, 2014

AP CONTENT API 2.8

PARAMETER

DESCRIPTION

EXAMPLE

source

One or more content creators. Multiple sources must be

separated by commas (an implied OR operator is used
between the sources).

AP,Image+Source

locations

A geographic location in the AP Geography vocabulary. The

list of AP Geography locations is available at
https://developer.ap.org/sites/default/files/APGeography.xls.
Note: Either the full name or the abbreviation of a
US state or Canadian province may be specified.

San+Francisco+CA

person

The name of a person who is featured in the content item.

Multiple names must be separated by commas (an implied
OR operator is used between the names). This parameter
may be used more than once in the URI to specify multiple
names that are connected by an implied AND operator. This
field is not applicable to video.

Tom+Cruise,Katie+
Holmes

photographer

The photographer's first and/or last name. This field is not

applicable to video or GraphicsBank.

Evan+Agostini

event

One or more words from the title of a specific event. This

field is not applicable to video or GraphicsBank.

MoMA+Film+Benefit

subject

Subject category in the AP Subject vocabulary. For a list of

top-level subjects, see Top-Level Subject Categories on
page 30. The full list of AP Subjects is available at
https://developer.ap.org/sites/default/files/APSubjects.xls.

Entertainment

imageId

One or more image ID numbers assigned to content items.

Multiple IDs must be separated by commas (an implied OR
operator is used between each image ID). This field is not
applicable to video.

111115013174,
111115175924

transref

Transmission reference number. This field is not applicable

to video or GraphicsBank.

DEL161

creationDate

The date when the content item was created, in the format
YYYY-MM-DD, YYYY-MM, YYYY or YYYY-MM-DDTHH:mmZ
where the value must be in Coordinated Universal Time
(UTC). For GraphicsBank items, this is the date of the news
event that the graphic illustrates.

2011-12-02
2011
2011-12-02T17:52Z

arrivalDate

The date when the content item was released, in the format
YYYY-MM-DD, YYYY-MM, YYYY or YYYY-MM-DDTHH:mmZ
where the value must be in Coordinated Universal Time
(UTC). By default, the entire AP Images or AP Video-US
collection is searched.

2011-12-02
2011-1202T17:52Z

showParametrics

By default, query facets that allow you to refine the original

search are returned for each content item at the entry level
only. When showParametrics=true is specified in the
request, the response also includes query facets in the
opensearch:Query elements at the feed level.

true

October 29, 2014

California
CA
Spain

AP CONTENT API 2.8

PARAMETER

DESCRIPTION

EXAMPLE

metadataLevel

The level of metadata to be included in search results. Valid options are:

1: includes all available metadata except for the query facets at the
feed level); this is the default option.
2: excludes <category> elements (except for urgency), query facets at
the feed and entry levels, and the <groupSet> element that contains
additional metadata in NewsML-G2 format.

count

The number of search results per page. The default is 25 results with a
maximum of 100 per page.

30

page

The page number within the set of search results. The default is 1.

sortby

Specifies how to sort the search results. Valid options are:

newsfeed

APPLIES TO
AP Images
(including
GraphicsBank)

VALUE
newest
newsfeed
highlights
oldest

Video

relevance
creationDate
creationDate/
sort.ascending

DISPLAYS...

The latest and most relevant items

first (this is the default for photos).
The latest items first.
The most relevant items first,
regardless of the time period.
The oldest and most relevant items
first.
The most relevant items first (this is
the default for video).
The latest items first.
The oldest items first.

Alternatively, you can use this parameter within the q parameter value.
For more information, see the Result Sorting section in Supported
Search Syntax on page 19.
Alternatively, you can use these parameters as metadata field names within the q parameter value. For more
information, see the Metadata Searches section in Supported Search Syntax on page 19.

Request Headers (Optional)

HEADER

DESCRIPTION

VALID VALUES

Accept

The MIME type of the returned data format (XML or

JSON). The default is application/atom+xml.

application/atom+xml
application/json

Accept-Encoding

Compresses the response to the gzip format.

gzip

Request URI Examples

SAMPLE URI

RETURNED RESULTS

https://api.ap.org/v2/search?apiKey={apiKey}&
q=Sarah+Jessica+Parker&creationDate=201211-10

Content items created on November 10, 2012

that match all of the specified keywords
(Sarah, Jessica and Parker)

https://api.ap.org/v2/search?apiKey={apiKey}&
person=Tom+Cruise&person=Katie+Holmes

Images featuring both Tom Cruise and Katie

Holmes

https://api.ap.org/v2/search?apiKey={apiKey}&
person=Tom+Cruise,Katie+Holmes

Images featuring either Tom Cruise or Katie

Holmes

October 29, 2014

AP CONTENT API 2.8

SAMPLE URI

RETURNED RESULTS

https://api.ap.org/v2/search?apiKey={apiKey}&
q=Tom+Cruise+AND+creationDate<2011

Content items created before 2011 that match all

of the specified keywords (Tom and Cruise)

https://api.ap.org/v2/search/video?apiKey=
{apiKey}&q=Tom+Cruise

Videos that match both keywords ("Tom" and

"Cruise")

https://api.ap.org/v2/search?apiKey={apiKey}&
q=football&contentSet=GraphicsBank

All GraphicsBank items that match the keyword

"football"

https://api.ap.org/v2/search?apiKey={apiKey}&
q=football&contentSet=GraphicsBank_Graphic&
creationDate=2013-11-09

All GraphicsBank graphics that match the

keyword "football" and illustrate a news event
that took place on November 9, 2013

Response
Returns the standard HTTP status code of 200 OK and search results in the specified format:

XML format that contains standard ATOM, OpenSearch, NewsML-G2 and XHTML elements

JSON format

Each result includes the content item ID, a limited set of metadata and links to all renditions of the
content item (for example, thumbnail, preview and high-resolution versions of a photo). For
information about error codes, see Error Codes on page 29.

Feed Descriptive Elements

XML ELEMENT

JSON PROPERTY

DESCRIPTION

A globally unique identifier for this set of search

results. The identifier consists of a
prefix "urn:tag:ap.org,2011-11-02:search-"
followed by the updated timestamp.

id

title

"title"

The original search terms.

updated

"updated"

The date and time (in W3C XML Schemas

xs:dateTime format) when the search results were
generated.
Contains the source of the search results.

author
name

The name of the organization that provided the

search results.

uri

The website of the organization that provided the

search results.

rights

Copyright line for the search results.

link

Provides links to navigate within the search results.

@rel="suggestedTerm"

"suggestedTerm"

(If applicable) A suggested term that can be used to

retry the search; for example, if the original search
term was misspelled.

@rel="first"

"firstpage"

Indicates a link to the first page of search results.

@rel="previous"

"previouspage"

Indicates a link to the previous page of search

results.

@rel="next"

"nextpage"

Indicates a link to the next page of search results.

October 29, 2014

AP CONTENT API 2.8

JSON PROPERTY

DESCRIPTION

@rel="last"

"lastpage"

Indicates a link to the last page of search results.

@rel="contentSet"

"contentSets"

Indicates a link to the results of this search for each of

the AP Images content sets: Editorial, Creative (RM),
Creative (RF), GraphicsBank, GraphicsBank_Graphic
and GraphicsBank_Photo.

@title

"title"

The suggested term or content set name.

@href

"href"

XML: The specific URL to a search result page or to

the results of this search for a particular content set.
JSON: The specific URL to the results of this search
for a particular content set.

XML ELEMENT

The MIME type of the data format returned when the

link in the href attribute is followed.

@type
opensearch:totalResults

"totalResults"

The number of results available for the current search.

opensearch:startIndex

"startIndex"

The index of the first search result in the current set of

results.

opensearch:itemsPerPage

"itemsPerPage"

The number of search results returned per page. The

default value is equal to the number of search results
on the current page.

opensearch:Query

"queries"

Contains the query that can be used to recreate these

search results or query facets that allow you to refine
the original search.
Note: Query facets at the feed level are
returned only when showParametrics=true is
specified in the request. For each facet type, the
search returns the top ten facets based on the
number of results matching that facet.

@role="facet.subject"

"role":
"facet.subject"

A query facet using the subject category name.

@role="facet.event"

"role":
"facet.event"

A query facet using the entry title.

@role="facet.person"

"role":
"facet.person"

A query facet using a person featured in the image.

@totalResults

"totalResults"

The number of search results matching a query facet.

@searchTerms

"searchTerms"

The search terms that can be used to refine the original

search.

@title

"title"

The query facet name.

Content Descriptive Elements

The following metadata elements are returned for each content item:
XML ELEMENT

JSON PROPERTY

DESCRIPTION

entry

"entries"

XML: Each "entry" element contains the data and metadata

associated with an individual feed entry.
JSON: The "entries" property contains all of the results on this page.

October 29, 2014

10

AP CONTENT API 2.8

XML ELEMENT

JSON PROPERTY

DESCRIPTION

id

"id"

XML: A unique identifier for the content item.

JSON: The canonical link (a link to the full
metadata for the content item).

title

"title"

The content item title.

updated

"updated"

The date and time (in W3C XML Schemas

xs:dateTime format) when the entry was updated.

published

"published"

The date and time (in W3C XML Schemas

xs:dateTime format) when the entry was created.

author/name

"source"

The name of the organization or individual that

provided source material for the content item.

rights

"rights"

Copyright line for the content item.

See <category>

"urgency"

The editorial priority assigned to the content (if

available). The possible values range from 1 (highest
priority) to 8 (lowest priority).

Numeric Legacy* Description

1
2
3
4
5
6
7
8

f
b
u
r
d
w
a
s

Flash
Bulletin
Urgent
Routine
Daily
Release at will
Weekday advance
Weekend advance

* Legacy values are not included in the API response and are
provided here for reference purposes only.

See <creditline>
in <groupSet>

"credit"

The name of the party or parties that are credited

with providing the content.

See <edNote> in
<groupSet>

"edNote"

Editorial instructions for processing the item. Do not

distribute this information to news consumers,
except where explicitly noted.

See <creator> in
<groupSet>

"photographer"

The party who created the content, such as a

photographer.

"id"

A code identifying the creator (or photographer) title.

"title"

The title of the party who created the content.

"name"

The name of the party who created the content.

"captionwriter"

The party who contributed to the content, such as a

caption writer.

"title"

The title of the party who contributed to the content.

"name"

The name of the party who contributed to the content.

"transmissionreference"

The reference ID value used to identify a transmission

of the content item across one or more mediums,
depending on the practices of the content distributor.

See
<contributor> in
<groupSet>
See <altId
type="idtype:
transmitRef">
in <groupSet>

October 29, 2014

11

AP CONTENT API 2.8

XML ELEMENT

JSON PROPERTY

DESCRIPTION

category

"categories"

XML: Multiple <category> elements are

returned. Each category contains one of the
following:
AP subject category
The media type of the search result
The editorial priority assigned to the
content (if available)
JSON: The categories property contains
all of the categories for this search result,
including AP subject categories and the
media type of the search result.

@term

"term"

The AP subject category or media type GUID.

@scheme

"scheme"

A URI for the vocabulary to which a term

belongs.

@label

"label"

A human-readable label for display in

applications.

"alternateLinks"
"contentLinks"

XML. Multiple <link> elements contain the

links to the full metadata and various
renditions of the content item, and search
results by image ID and transmission
reference number.
JSON. The alternateLinks property
contains the links to search results by image
ID and transmission reference number. The
contentLinks property contains the links to
the various renditions of the content item.

@rel="canonical"

See id

Indicates a link to the full metadata for the

current entry. By default, the full metadata is
provided in the NewsML-G2 format.

@rel="alternate.imageid"

"alternate.imageid"

Indicates a link to the results of a search by the

image ID number assigned to the content item.

@rel="alternate.transref"

"alternate.transref"

Indicates a link to the results of a search by the

transmission reference number assigned to the
content item.

@rel="thumbnail"

"thumbnail"

Indicates a link to the content item thumbnail

(if available).

@rel="preview"

"preview"

Indicates a link to the content item preview (if

available).

@rel="main"

"main"

Indicates a link to the main rendition of the

content item.

link

October 29, 2014

12

AP CONTENT API 2.8

XML ELEMENT

JSON PROPERTY

DESCRIPTION

@href

"href"

The specific URL to one of the following:

The content item metadata.
Search results by image ID.
Search results by transmission reference number
of the content item.
A content item rendition. You can specify the
value of the format parameter (located at the end
of the URL) as the value of the format parameter
in the Item Rendition request. For more
information, see Item Rendition Download
Method on page 26.

@type

"type"

The MIME type of the data format returned when the

link in the href attribute is followed. You can
specify the MIME type of the content item rendition
in the Accept header of the Item Rendition request.
For more information, see Item Rendition
Download Method on page 26.

@title

"title"

The name of the content item rendition that can be

used for posting on a website.

See @height and

@width in
<remoteContent> in
<groupSet>

"height"

Height of image/video in pixels.

"width"

Width of image/video in pixels.

content

"contentxhtml"

For photos and graphics: contains the content

item caption.
For video: a script and/or a caption (if available).
Indicates that the content is formatted as XHTML.

@type="xhtml"

Contain additional metadata for the content item in

NewsML-G2 format.

groupSet and group

The API reference for the content item.

itemRef/@href
edNote

See ednote

Editorial instructions for processing the item. Do not

distribute this information to news consumers,
except where explicitly noted.

creator

See "photographer"

The party who created the content, such as a

photographer.

@literal

A code identifying the creator (or photographer) title.

@jobtitle

The title of the party who created the content.

@role

The role of the party who created the content.

name

The name of the party who created the content.

contributor

See "captionwriter"

The party who contributed to the content, such as a

caption writer.

@jobtitle

The title of the party who contributed to the content.

@role

The role of the party who contributed to the content.

name

The name of the party who contributed to the content.

October 29, 2014

13

AP CONTENT API 2.8

XML ELEMENT

JSON PROPERTY

DESCRIPTION

altId/@type

See
transmissionreference

One of the following alternative IDs, each in its

own <altId> element:
transmitRef: the reference ID value used to
identify a transmission of the content item
across one or more mediums, depending on
the practices of the content distributor.
friendlyKey: a human-readable ID that
uniquely identifies a content item.
recordSequenceNumber: the content item
revision number (0 for the initial version, 1
for the first revision, 2 for the second
revision and so on).
itemId: a unique ID for the chain of
revisions that comprise a content item.

creditline

See credit

The name of the party or parties that are

credited with providing the content.
Indicates a link to the main, preview or
thumbnail rendition of a content item.

remoteContent
@href

The specific URL to the main, preview or

thumbnail rendition of a content item.

@residref

Resource Identifier Reference used to identify

the content item rendition.

@type

The MIME type associated with the content

item data (for example, image/jpeg).

@rendition

The content item rendition (for example,

highRes, preview or thumbnail).

@contenttype

The MIME type associated with the content

item data (for example, image/jpeg).

@format

The format of the content item data (for

example, JPEG_Baseline).
See "width" and
"height" under
"contentLinks"

Width of image/video in pixels.

"queries"

Additional query facets for the entry that can

be used to refine the original search.

@role="facet.person"

"role": "facet.person"

A query facet using a person featured in the

image.

@role="facet.event"

"role": "facet.event"

A query facet using the title of the current

entry.

@searchTerms

"searchTerms"

The search terms that can be used to refine the

original search.

@title

"title"

The featured persons name or the entry title.

@width
@height
opensearch:Query

October 29, 2014

Height of image/video in pixels.

14

AP CONTENT API 2.8

Sample Response
XML
The following example shows the results of a keyword search for Tom Cruise in the XML format
(only one result is shown for brevity). Dark gray shading indicates query facets that are returned only
when the showParametrics=true parameter is specified in the request. Light gray shading indicates
additional metadata that can be excluded by specifying the metadataLevel=2 parameter.
- <feed xmlns="http://www.w3.org/2005/Atom" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
<id>urn:tag:ap.org,2011-11-02:search-2012-01-06T20:31:11.059Z</id>
<title>Tom Cruise</title>
<updated>2012-01-06T20:31:11.059Z</updated>
- <author>
<name>The Associated Press</name>
<uri>http://www.ap.org</uri>
</author>
<rights>Copyright 2012 The Associated Press. All rights reserved.</rights>
<link rel="first" href="https://api.ap.org/v2/search?q=Tom+Cruise&page=1" type="application/atom+xml" />
<link rel="next" href="https://api.ap.org/v2/search?q=Tom+Cruise&page=2" type="application/atom+xml" />
<link rel="last" href="https://api.ap.org/v2/search?q=Tom+Cruise&page=60" type="application/atom+xml" />
<link rel="contentSet" title="Editorial" href="https://api.ap.org/v2/search?q=Tom+Cruise&contentSet=editorial"
type="application/atom+xml" />
<link rel="contentSet" title="Creative (RM)" href="https://api.ap.org/v2/search?q=Tom+Cruise&contentSet=creativerm"
type="application/atom+xml" />
<link rel="contentSet" title="Creative (RF)" href="https://api.ap.org/v2/search?q=Tom+Cruise&contentSet=creativerf"
type="application/atom+xml" />
<opensearch:totalResults>1494</opensearch:totalResults>
<opensearch:startIndex>1</opensearch:startIndex>
<opensearch:itemsPerPage>25</opensearch:itemsPerPage>
<opensearch:Query role="facet.subject" totalResults="1060" title="ENTERTAINMENT" searchTerms="Tom Cruise AND
subject="ENTERTAINMENT"" />
<opensearch:Query role="facet.subject" totalResults="1021" title="ARTS AND ENTERTAINMENT" searchTerms="Tom Cruise
AND subject="ARTS AND ENTERTAINMENT"" />
<opensearch:Query role="facet.subject" totalResults="991" title="CELEBRITY" searchTerms="Tom Cruise AND
subject="CELEBRITY"" />
<opensearch:Query role="facet.subject" totalResults="493" title="MOVIES" searchTerms="Tom Cruise AND
subject="MOVIES"" />
<opensearch:Query role="facet.subject" totalResults="454" title="MOVIE PREMIERES" searchTerms="Tom Cruise AND
subject="MOVIE PREMIERES"" />
<opensearch:Query role="facet.subject" totalResults="62" title="CELEBRITY RED CARPET" searchTerms="Tom Cruise AND
subject="CELEBRITY RED CARPET"" />

<opensearch:Query role="facet.event" totalResults="86" title="TOM CRUISE & KATIE HOLMES IN NYC" searchTerms="Tom
Cruise AND event="TOM CRUISE & KATIE HOLMES IN NYC"" />
<opensearch:Query role="facet.event" totalResults="85" title="PREMIERE VALKYRIE NY" searchTerms="Tom Cruise AND
event="PREMIERE VALKYRIE NY"" />
<opensearch:Query role="facet.event" totalResults="63" title="MISSION: IMPOSSIBLE - GHOST PROTOCOL PREMIERE"
searchTerms="Tom Cruise AND event="MISSION: IMPOSSIBLE - GHOST PROTOCOL PREMIERE"" />

<opensearch:Query role="facet.person" totalResults="664" title="TOM CRUISE" searchTerms="Tom Cruise AND

person="TOM CRUISE"" />
<opensearch:Query role="facet.person" totalResults="177" title="KATIE HOLMES" searchTerms="Tom Cruise AND
person="KATIE HOLMES"" />
<opensearch:Query role="facet.person" totalResults="42" title="OPRAH WINFREY" searchTerms="Tom Cruise AND
person="OPRAH WINFREY"" />

- <entry>
<id>https://api.ap.org/v2/item/fedf6ff0f6564fc29449f189d9242349</id>
<title>Britain Mission Impossible Ghost Protocol</title>
<updated>2012-01-09T15:31:13.793Z</updated>
<published>2012-01-05T17:33:53Z</published>
- <author>
<name>AP</name>
</author>
<rights>Copyright 2011 The Associated Press. All rights reserved. This material may not be published, broadcast, rewritten
or redistributed.</rights>
<category term=c706572879441004880dba7Fa5283c3e scheme=http://cv.ap.org/id/ label=Photo />
<category term="b4ed19d87e5c10048565df092526b43e" scheme="http://cv.ap.org/id/" label="Celebrity" />

October 29, 2014

15

AP CONTENT API 2.8

<category term="854509a889f01004818ed56c852d093e" scheme="http://cv.ap.org/id/" label="Celebrity red carpet" />

<category term="7553a0f08a671004809cbe215f24353e" scheme="http://cv.ap.org/id/" label="Movie premieres" />
<category term="5b4319707dd310048b23df092526b43e" scheme="http://cv.ap.org/id/" label="Entertainment" />
<category term="16cb0ba3e6d24d97ace39f5a1924669a" scheme="http://cv.ap.org/id/" label="Arts and entertainment" />
<category term="c189ae6088be10048dcfb097165a0203" scheme="http://cv.ap.org/id/" label="Movies" />
<category scheme="http://cv.ap.org/urgency/" label="5" />
<link rel="canonical" href="https://api.ap.org/v2/item/fedf6ff0f6564fc29449f189d9242349" />
<link rel="alternate.imageid" href="https://api.ap.org/v2/search/photo?imageId=111213124683" />
<link rel="alternate.transref" href="https://api.ap.org/v2/search?transref=NYOTK&arrivalDate=2012-01-09" />
<link rel="main" href="https://bapi.ap.org/v2/item/photo/fedf6ff0f6564fc29449f189d9242349/Main?format=jpeg
&filename=fedf6ff0f6564fc29449f189d9242349_Britain Mission Impossible Ghost Protocol_3264x4896.jpg"
type="image/jpeg" title="Full-Resolution (JPG)" />
<link rel="thumbnail" href="https://bapi.ap.org/v2/item/photo/fedf6ff0f6564fc29449f189d9242349/Thumbnail
?format=jpeg&filename=fedf6ff0f6564fc29449f189d9242349_Britain Mission Impossible Ghost Protocol_85x128.jpg"
type="image/jpeg" title="Thumbnail (JPG)" />
<link rel="preview" href="https://bapi.ap.org/v2/item/photo/fedf6ff0f6564fc29449f189d9242349/Preview
?format=jpeg&filename=fedf6ff0f6564fc29449f189d9242349_Britain Mission Impossible Ghost Protocol_341x512.jpg"
type="image/jpeg" title="Preview (JPG)" />
- <content type="xhtml">
- <div xmlns="http://www.w3.org/1999/xhtml">
<p>U.S actor Tom Cruise arrives on the red carpet for the UK Premiere of Mission: Impossible Ghost Protocol, at a
central London cinema, Tuesday, Dec. 13, 2011. (AP Photo/Joel Ryan)</p>
</div>
</content>
- <groupSet root="fedf6ff0f6564fc29449f189d9242349-G1" xmlns="http://iptc.org/std/nar/2006-10-01/">
- <group id="fedf6ff0f6564fc29449f189d9242349-G1" role="group:main">
- <itemRef href="https://api.ap.org/v2/item/fedf6ff0f6564fc29449f189d9242349">
<edNote>For editorial use. Special rates may apply. Please contact your AP representative with
questions.</edNote>
- <creator literal="STF" jobtitle="aptitle:STAFF" role="aprol:photographer">
<name>Joel Ryan</name>
</creator>
- <contributor jobtitle="aptitle:CaptionWriter" role="aprol:captionwriter">
<name>JR</name>
</contributor>
<altId type="idtype:transmitRef">NYOTK</altId>
<altId type="ap:friendlyKey">111213124683</altId>
<altId type="ap:recordSequenceNumber">0</altId>
<altId type="ap:itemId">fedf6ff0f6564fc29449f189d9242349</altId>
<creditline>ASSOCIATED PRESS</creditline>
<remoteContent href="http://bapi.ap.org/v2/item/photo/fedf6ff0f6564fc29449f189d9242349/Main?format=
jpeg&filename=fedf6ff0f6564fc29449f189d9242349_Britain Mission Impossible Ghost Protocol_3264x4896.jpg"
residref="dc267e5a84837100030f6a7067006aad" contenttype="image/jpeg" rendition="rnd:highRes"
size="1951322" format="frmt:JPEG_Baseline" width="3264" height="4896" />
<remoteContent href="http://bapi.ap.org/v2/item/photo/fedf6ff0f6564fc29449f189d9242349/Preview
?format=jpeg&filename=fedf6ff0f6564fc29449f189d9242349_Britain Mission Impossible Ghost
Protocol_341x512.jpg" residref="dc26a37e84837100030f6a706700f47d" contenttype="image/jpeg"
format="frmt:JPEG_Baseline" rendition="rnd:preview" width="341" height="512" />
<remoteContent href="http://bapi.ap.org/v2/item/photo/fedf6ff0f6564fc29449f189d9242349/Thumbnail
?format=jpeg&filename=fedf6ff0f6564fc29449f189d9242349_Britain Mission Impossible Ghost
Protocol_85x128.jpg" residref="dc26967b84837100030f6a7067001dfd" contenttype="image/jpeg"
format="frmt:JPEG_Baseline" rendition="rnd:thumbnail" width="85" height="128" />
</itemRef>
</group>
</groupSet>
<opensearch:Query role="facet.person" searchTerms="Tom Cruise AND person="Tom Cruise"" title="Tom Cruise" />
<opensearch:Query role="facet.event" searchTerms="Tom Cruise AND event="Britain Mission Impossible Ghost Protocol""
title="Britain Mission Impossible Ghost Protocol" />
</entry>

</feed>

October 29, 2014

16

AP CONTENT API 2.8

JSON
The following example shows the results of a keyword search for Tom Cruise in the JSON format
(only one result is shown for brevity). Dark gray shading indicates query facets that are returned only
when the showParametrics=true parameter is specified in the request. Light gray shading indicates
additional metadata that can be excluded by specifying the metadataLevel=2 parameter.
{
"title": "Tom Cruise",
"updated": "2012-01-06T20:31:11.059Z" ,
"firstpage": "https://api.ap.org/v2/search?q=Tom+Cruise&page=1" ,
"nextpage": "https://api.ap.org/v2/search?q=Tom+Cruise&page=2" ,
"lastpage": "https://api.ap.org/v2/search?q=Tom+Cruise&page=60" ,
"contentSets": [
{"href": "https://api.ap.org/v2/search?q=Tom+Cruise&contentSet=editorial", "title": "Editorial"} ,
{"href": "https://api.ap.org/v2/search?q=Tom+Cruise&contentSet=creativerm", "title": "Creative (RM)"},
{"href": "https://api.ap.org/v2/search?q=Tom+Cruise&contentSet=creativerf", "title": "Creative (RF)"}
],
"totalResults": 1494 ,
"startIndex": 1 ,
"itemsPerPage": 25 ,
"queries": [
{"role": "facet.subject", "totalResults": "1060", "title": "ENTERTAINMENT", "searchTerms": "Tom Cruise AND
subject='ENTERTAINMENT'"} ,
{"role": "facet.subject", "totalResults": "1021", "title": "ARTS AND ENTERTAINMENT" , "searchTerms": "Tom Cruise AND
subject='ARTS AND ENTERTAINMENT'"},
{"role": "facet.subject", "totalResults": "991", "title": "CELEBRITY", "searchTerms": "Tom Cruise AND subject='CELEBRITY'"} ,
{"role": "facet.subject", "totalResults": "493", "title": "MOVIES", "searchTerms": "Tom Cruise AND subject='MOVIES'"}
],
"entries": [
{"id": "https://api.ap.org/v2/item/fedf6ff0f6564fc29449f189d9242349" ,
"title": "Britain Mission Impossible Ghost Protocol",
"updated": "2012-01-09T15:31:13.793Z",
"published": "2012-01-05T17:33:53Z",
"source": "AP",
"rights": "Copyright 2011 The Associated Press. All rights reserved. This material may not be published, broadcast, rewritten
or redistributed.",
"urgency": "5",
"credit": "ASSOCIATED PRESS",
"ednote": "For editorial use. Special rates may apply. Please contact your AP representative with questions.",
"transmissionreference": "NYOTK",
"photographer":
{
"id": "STF",
"title": "STAFF",
"name": "Joel Ryan"
},
"captionwriter":
{
"title": "Caption Writer",
"name": "JR"
},
"categories": [
{"term": "c706572879441004880dba7Fa5283c3e", "scheme": "http://cv.ap.org/id/", "label": "Photo"},
{"term": "b4ed19d87e5c10048565df092526b43e", "scheme": "http://cv.ap.org/id/", "label": "Celebrity"},
{"term": "16cb0ba3e6d24d97ace39f5a1924669a", "scheme": "http://cv.ap.org/id/", "label": "Arts and entertainment"}
],
"alternateLinks": [
{"alternate.imageid": "https://api.ap.org/v2/search/photo?imageId=111213124683"},
{"alternate.transref": "https://api.ap.org/v2/search?transref=NYOTK&arrivalDate=2012-01-09"}
],
"contentxhtml": "<p>U.S actor Tom Cruise arrives on the red carpet for the UK Premiere of Mission: Impossible Ghost
Protocol, at a central London cinema, Tuesday, Dec. 13, 2011. (AP Photo/Joel Ryan)</p>",
"contentLinks":
[
{
"rel": "main",
"href": "https://bapi.ap.org/v2/item/photo/fedf6ff0f6564fc29449f189d9242349/Main?format=jpeg&filename=

October 29, 2014

17

AP CONTENT API 2.8

fedf6ff0f6564fc29449f189d9242349_Britain Mission Impossible Ghost Protocol_3264x4896.jpg",

"type": "image/jpeg",
"title": "Full-Resolution (JPG)",
"height": 3264,
"width": 4896
},
{
"rel": "thumbnail",
"href": "https://bapi.ap.org/v2/item/photo/fedf6ff0f6564fc29449f189d9242349/Thumbnail?format=jpeg&filename=
fedf6ff0f6564fc29449f189d9242349_Britain Mission Impossible Ghost Protocol_85x128.jpg",
"type": "image/jpeg",
"title": "Thumbnail (JPG)",
"height": 85,
"width": 128
},
{
"rel": "preview",
"href": "https://bapi.ap.org/v2/item/photo/fedf6ff0f6564fc29449f189d9242349/Preview?format=jpeg&filename=
fedf6ff0f6564fc29449f189d9242349_Britain Mission Impossible Ghost Protocol_341x512.jpg",
"type": "image/jpeg",
"title": "Preview (JPG)",
"height": 341,
"width": 512
}],
"queries": [
{ "role": "facet.person", "searchTerms": "Tom Cruise AND person='Tom Cruise'", "title": "Tom Cruise"},
{ "role": "facet.event", "searchTerms": "Tom Cruise AND event='Britain Mission Impossible Ghost Protocol'", "title": "Britain
Mission Impossible Ghost Protocol"}
]
}
]
}

October 29, 2014

18

AP CONTENT API 2.8

SUPPORTED SEARCH SYNTAX

Important: This section applies only to specifying the query expression (the value of the q
parameter in search requests). Make sure that the query expression is URL-encoded. For
example, the URL-encoded value of the sample query child psychology magazine is
child+"psychology+magazine.
SEARCH TYPE

DESCRIPTION

Basic
Keywords

A basic query contains one or more words and no operators.

SAMPLE QUERY
Iraq
iraq
Iraq Iran Iraq

Wildcard
Searches

Finds items containing the word Iraq and related word

variations, such as Iraqi, but not Iran.
Returns the same results as Iraq (case is ignored).
Returns the same results as Iraq Iran (repeated words are
ignored).

Wildcards are useful when you are not sure of the spelling or exact name of a desired
item. You can use the following wildcards in your query:
Question mark (?) to substitute any single alphanumeric character in a query term.
Asterisk (*) to substitute none, one or more characters at the beginning or end of a
word.
Important: A wildcard character must be preceded and followed by either
an alphanumeric character or a space.
SAMPLE QUERY
la?er
pharma*
*view
*ploy*

Exact
Phrase

RETURNED RESULTS

FINDS

Later, layer, lager, etc.

pharmacy, pharmaceutical, pharmacist
review, overview, preview
deployed, deployment, employer, employee

Use quotation marks to specify exact phrases:

SAMPLE QUERY
"Scotland Yard"

"scotland yard"
child
psychology
magazine

RETURNED RESULTS

Finds items containing the entire exact phrase Scotland Yard,

not just the word Scotland or the word Yard. This also prevents
word stemming, so Scottish Yards or Scotland's Yardley will not
match.
Returns the same results as Scotland Yard (case is ignored in
quoted text).
Finds items containing both child and psychology magazine
including child psychology magazine and childrens psychology
magazine (stemming is applied to the word child).

To use a stop word (for example, "Case", "has", "after", "near") in a search query,
enclose it in quotation marks. For example, use "The 2009 Olympics" instead of The
2009 Olympics, and "Yahoo!" instead of Yahoo!
Note: If quotation marks surround a search term that includes a wildcard
(like ? or *), the quotation marks are ignored.

October 29, 2014

19

AP CONTENT API 2.8

SEARCH TYPE

DESCRIPTION

Boolean
Operators

You can use the following Boolean operators between keywords:

AND to narrow a search matching all of the keywords.
OR to broaden a search by matching any of the keywords.
NOT to narrow a search by excluding a keyword.
SAMPLE QUERY
Queen AND Elizabeth

California OR wildfires
OR earthquakes
strike NOT baseball

RETURNED RESULTS

Finds items containing both the words Queen and

Elizabeth (as in Queen Elizabeth II or Elizabeth, Queen of
England).
Finds items containing any of these words: California or
wildfires or earthquakes.
Finds items containing the word strike (such as a transit
strike or airline strike) but not word baseball (such as
baseball strike).

To specify the order in which your search terms are processed, surround the first set
that you want processed with parentheses:
SAMPLE QUERY
(media OR
censorship) NOT
radio
wildfires AND
(earthquakes
NOT California)

wildfires AND
(earthquakes OR
California)
wildfires AND
earthquakes OR
California

RETURNED RESULTS

Finds items containing either of the words media or

censorship, then excludes those that also contain the word
radio.
Finds items containing the word earthquakes but not
California, and then returns items that also contain the word
wildfires. Items about wildfires and earthquakes would be
returned, but not about California wildfires. In this example,
leaving out the parentheses does not change the results.
Finds items containing either the words wildfires and
earthquakes, or wildfires and California. In this example,
leaving out the parentheses does change the results (see
below).
Finds items containing either the words wildfires and
earthquakes or the word California.

The Search method uses standard Boolean precedence rules and searches for content
items in the following order:
1. Words surrounded by parentheses.
2. Words surrounded by quotation marks.
3. Words connected by NOT, AND and finally, OR.
Metadata
Searches

You can narrow your search to a specific metadata field:

SAMPLE QUERY
headline=Chancellor
headline=Chancellor
AND event=Chancellor

October 29, 2014

RETURNED RESULTS

Finds items containing the word Chancellor in the image

headline.
Finds items containing the word Chancellor in the image
headline and the event title.

20

AP CONTENT API 2.8

SEARCH TYPE

DESCRIPTION

Metadata
Searches
(continued)

You can use the following comparison operators:

OPERATOR
=
<>
<
>
<=
>=

DESCRIPTION

Equal to
Not equal to
Less than
Greater than
Less than or equal to
Greater than or equal to

URL-ENCODED VALUE
%3D
<>
<
>
<%3D
>%3D

For example, you can use these operators to specify dates and date ranges as part of
the q parameter value:
SAMPLE QUERY
arrivalDate>=2011-12-02
creationDate>2012-01 AND
creationDate<2012-11
arrivalDate=2012-0103T17:52Z

RETURNED RESULTS

Finds items that arrived on or after December 12,

2011.
Finds items created during the months between
January and November 2012.
Finds items that arrived at 17:52 UTC on January 3,
2012.

Metadata fields can be combined with Boolean operators or wildcards to narrow or

widen a search.
SAMPLE QUERY
source=(AP or CP) NOT
("Queen Elizabeth II" OR
"Elizabeth, Queen of England")
imageId=X01* AND
headline<>fire

RETURNED RESULTS

Finds items that originated by AP or Canadian

Press (CP) that are not about Queen Elizabeth II.

Finds items with image ID numbers that begin

with X01 and do not include the word fire in the
headline.
Some commonly used metadata fields to enter in search expressions include:
The following metadata fields that are also used as search request URI parameters:
source, person, photographer, event, subject, imageId, transref, creationDate,
arrivalDate and locations. For more information, see Request URI Parameters
on page 6.
Additional metadata fields:
FIELD NAME
keywords
headline

Result
Sorting

DESCRIPTION

A multi-word field used to expedite content searching.

A brief synopsis of the content item.

You can use the sortby parameter and its values within the q parameter value.
SAMPLE QUERY
person="Tom Cruise" sortby
creationDate

RETURNED RESULTS

Finds items featuring Tom Cruise and displays

the newest items first.
For more information, see Request URI Parameters on page 6.

October 29, 2014

21

AP CONTENT API 2.8

CONTENT ITEM
ITEM METADATA METHOD
Important: This section is provided for reference purposes. Use the item metadata links
that are available in search results.

Description
Returns the content item data for the specified GUID, including metadata and links to all renditions of
the content item (for example, thumbnail, preview and high-resolution versions of a photo).

Request
METHOD

REQUEST URI

GET

https://api.ap.org/{version}/item/{id}?apiKey={apiKey}[&format={format}]

Request URI Parameters

Required Parameters
PARAMETER

DESCRIPTION

VALID VALUE

version

The API version. Currently, the only valid value is v2.

v2

id

The GUID of a content item (not case-sensitive).

Any valid 32-character

GUID of a content item

Optional Parameter
PARAMETER

DESCRIPTION

VALID VALUE

format

The format of the returned content item data. The requested output
format can be specified either as the format parameter value or as the
format MIME type in the request Accept header (the format parameter
value takes precedence over the Accept header value). If no format is
specified as the format parameter value or in the Accept header,
NewsML-G2 is returned.

g2

Request Headers (Optional)

HEADER

DESCRIPTION

VALID VALUES

Accept

The MIME type of the returned data format. The default

is NewsML-G2 (application/vnd.iptc.g2.newsitem+xml).

application/vnd.iptc.
g2.newsitem+xml

Accept-Encoding

Compresses the response to the gzip format.

gzip

Request URI Example

https://api.ap.org/v2/item/fedf6ff0f6564fc29449f189d9242349?format=g2&apiKey={apiKey}

Response
Returns the standard HTTP status code of 200 OK and an XML document with the content item
data for the specified GUID. For information about error codes, see Error Codes on page 29.
October 29, 2014

22

AP CONTENT API 2.8

Sample Response
The content item data is returned as XML in the NewsML-G2 format.

NewsML-G2
NewsML-G2 is a news exchange format developed by the International Press Telecommunications
Council (IPTC). For more information, please visit
http://www.iptc.org/site/News_Exchange_Formats/NewsML-G2/. The current AP Content API
implementation of NewsML-G2 is based on version 2.10 and includes AP proprietary metadata.
News Message Structure
A NewsML-G2 News Message returned by the AP Images API has the following structure:
1. Header. General information about the News Message that includes standard NewsML-G2
elements. For more information, refer to the IPTC G2 Implementation Guide at
http://www.iptc.org/std/NewsML-G2/2.13/documentation/IPTC-G2Implementation_Guide_5.0.pdf.
2. Item Set. Contains a G2 News Item (described in more detail in the following section).
NEWS MESSAGE
- <newsMessage xmlns="http://iptc.org/std/nar/2006-10-01/">
<!-- APImages API NewsML G2 -->
- <header>
<sent>2012-01-05T17:33:53Z</sent>
<sender>ap.org</sender>
</header>
- <itemSet>
+ <newsItem guid="tag:ap.org,2011:fedf6ff0f6564fc29449f189d9242349-photo" version="1" standard="NewsMLG2" standardversion="2.10" conformance="power" xmlns:xhtml="http://www.w3.org/1999/xhtml" >
</itemSet>
</newsMessage>

1
2

News Item Structure

1. The top-level <newsItem> element. This element contains a GUID and version number for
the document, catalog references and copyright information.
2. Management metadata. The <itemMeta> element contains management metadata, such as
the item class, provider, publishing status, timestamps, the generator version used to create the
news item, the versions and labels of the AP vocabularies represented in the response (for
example, AP Subject, AP Geography), the services for distributing the news item, editorial note
and signal.
3. Content metadata. The <contentMeta> element contains:
A. Administrative metadata, such as urgency, timestamps, creator (photographer),
contributor (caption writer), location, source, alternative IDs and language.
B. Descriptive metadata, such as subjects, slugline, headline, natural language author/creator
information (in one or more <by> elements), creditline, keywords, caption and overline.
The caption appears in the <description role="drol:caption"> element. The overline
appears in the <description role="drol:overline"> element. For more information about
subject categories, please refer to the list of AP Subjects posted at
http://developer.ap.org/sites/default/files/APSubjects.xls.
4. Content. The <contentSet> element contains links to the main, preview and thumbnail
renditions.

October 29, 2014

23

AP CONTENT API 2.8

- <newsItem guid="tag:ap.org,2011:fedf6ff0f6564fc29449f189d9242349-photo" version="1"

standard="NewsML-G2" standardversion="2.10" conformance="power">
<catalogRef href="http://www.iptc.org/std/catalog/catalog.IPTC-G2-Standards_6.xml" />
<catalogRef href="http://cv.ap.org/customer/cv/catalog4customers-1.xml" />
- <rightsInfo>
<copyrightHolder literal="AP" />
<copyrightNotice>Copyright 2011 The Associated Press. All rights reserved. This material may not be
published, broadcast, rewritten or redistributed.</copyrightNotice>
</rightsInfo>
- <itemMeta>
<itemClass qcode="ninat:picture" />
<provider literal="AP" />
<versionCreated>2012-01-05T17:33:53Z</versionCreated>
<pubStatus qcode="stat:usable" />
<generator versioninfo="2.9.0.C15803" role="apgen:runtime">APPL_2_NEWSML_ENTRY</generator>
<generator versioninfo="2994" role="apgen:tagging">AP Subject</generator>
<generator versioninfo="3002" role="apgen:tagging">AP Party</generator>
<generator versioninfo="2975" role="apgen:tagging">AP Geography</generator>
<service qcode="selector:-----" />
<service qcode="apcycle:AP" />

<edNote>For editorial use. Special rates may apply. Please contact your AP representative with
questions.</edNote>
<signal qcode="apsig:consumerready" />
</itemMeta>
- <contentMeta>
<urgency>5</urgency>
<contentCreated>2012-01-05T17:33:53Z</contentCreated>
<contentModified>2012-01-05T17:33:53Z</contentModified>
- <creator literal="STF" jobtitle="aptitle:STAFF" role="aprol:photographer">
<name>Joel Ryan</name>
</creator>
- <contributor jobtitle="aptitle:CaptionWriter" role="aprol:captionwriter">
<name>JR</name>
</contributor>
- <located type="cptype:city">
<name>London</name>
- <broader type="cptype:country">
<name>GBR XEN</name>
</broader>
- <geoAreaDetails>
<position latitude="51.50853" longitude="-0.12574" />
</geoAreaDetails>
</located>
- <infoSource role="crole:source">
<name>AP</name>
</infoSource>
- <infoSource type="crole:filingsource">
<name>AP</name>
</infoSource>
<altId type="idtype:transmitRef">NYOTK</altId>
<altId type="ap:friendlyKey">111213124683</altId>
<altId type="ap:recordSequenceNumber">0</altId>
<altId type="ap:itemId">fedf6ff0f6564fc29449f189d9242349</altId>
<altId type="ap:recordId">6834b04959fb484c8032149682d0b9ea</altId>
<language tag="en-us" />
<keyword role="krole:index">Tom Cruise</keyword>
- <subject type="cpnat:abstract" qcode="apcategorycode:I">
<name>International News</name>
</subject>
- <subject type="cpnat:abstract" qcode="apsuppcat:ENT">
<name>Entertainment</name>
</subject>
- <subject type="cpnat:abstract" qcode="apsubject:b4ed19d87e5c10048565df092526b43e"
why="why:direct" creator="apsubcreator:Teragram">

October 29, 2014

24

AP CONTENT API 2.8

<name>Celebrity</name>
- <broader qcode="apsubject:5b4319707dd310048b23df092526b43e">
<name>Entertainment</name>
</broader>
</subject>
- <subject type="cpnat:abstract" qcode="apsubject:854509a889f01004818ed56c852d093e"
why="why:direct" creator="apsubcreator:Teragram">
<name>Celebrity red carpet</name>
- <broader qcode="apsubject:b4ed19d87e5c10048565df092526b43e">
<name>Celebrity</name>
</broader>
</subject>
- <subject type="cpnat:abstract" qcode="apsubject:7553a0f08a671004809cbe215f24353e"
why="why:direct" creator="apsubcreator:Teragram">
<name>Movie premieres</name>
- <broader qcode="apsubject:c189ae6088be10048dcfb097165a0203">
<name>Movies</name>
</broader>
</subject>

- <subject type="cpnat:person" qcode="apperson:00f3318c4bae4a8da43016d8573c28be"

creator="apsubcreator:Teragram">
<name>Tom Cruise</name>
</subject>
- <subject type="cpnat:geoArea" qcode="apgeography:66219fb07d5b100482e2c076b8e3055c"
why="why:direct" creator="apsubcreator:Teragram">
<name>United Kingdom</name>
</subject>
- <subject type="cpnat:geoArea" qcode="apgeography:7a55e0187eff10048492df092526b43e"
why="why:direct" creator="apsubcreator:Teragram">
<name>London</name>
</subject>
- <subject type="cpnat:geoArea" qcode="apgeography:6618c9f87d5b10048202c076b8e3055c"
why="why:ancestor" creator="apsubcreator:Teragram">
<name>Western Europe</name>
</subject>
- <subject type="cpnat:geoArea" qcode="apgeography:661850e07d5b100481f4c076b8e3055c"
why="why:ancestor" creator="apsubcreator:Teragram">
<name>Europe</name>
</subject>
- <subject type="cpnat:geoArea" qcode="apgeography:df4691387d6b10048fdeba7fa5283c3e"
why="why:ancestor" creator="apsubcreator:Teragram">
<name>England</name>
</subject>
<slugline>Britain Mission Impossible Ghost Protocol</slugline>
<headline xml:lang="en-us">Britain Mission Impossible Ghost Protocol</headline>
<by>Joel Ryan</by>
<by>JR</by>
<creditline>ASSOCIATED PRESS</creditline>
<description xml:lang="en-us" role="drol:caption">U.S actor Tom Cruise arrives on the red carpet for the
UK Premiere of Mission: Impossible Ghost Protocol, at a central London cinema, Tuesday, Dec. 13, 2011
(AP Photo/Joel Ryan).</description>
<description xml:lang="en-us" role="drol:overline">Tom Cruise</description>
</contentMeta>
- <contentSet>
<remoteContent residref="dc267e5a84837100030f6a7067006aad"
href="https://bapi.ap.org/v2/item/photo/fedf6ff0f6564fc29449f189d9242349/Main?format=jpeg"
residref="dc267e5a84837100030f6a7067006aad" rendition="rnd:highRes" size="1951322"
contenttype="image/jpeg" format="frmt:JPEG_Baseline" width="3264" height="4896" orientation="2" />
<remoteContent residref="dc26a37e84837100030f6a706700f47d"
href="https://bapi.ap.org/v2/item/photo/fedf6ff0f6564fc29449f189d9242349/Preview?format=jpeg"
residref="dc26a37e84837100030f6a706700f47d" rendition="rnd:preview" contenttype="image/jpeg"
format="frmt:JPEG_Baseline" width="341" height="512" />
<remoteContent residref="dc26967b84837100030f6a7067001dfd"
href="https://bapi.ap.org/v2/item/photo/fedf6ff0f6564fc29449f189d9242349/Thumbnail?format=jpeg"
residref="dc26967b84837100030f6a7067001dfd" rendition="rnd:thumbnail" contenttype="image/jpeg"
format="frmt:JPEG_Baseline" width="85" height="128" />
</contentSet>
</newsItem>

October 29, 2014

25

AP CONTENT API 2.8

ITEM RENDITION DOWNLOAD METHOD

Important: This section is provided for reference purposes. Use the item rendition
download links that are available in search results.

Description
Returns the specified rendition of a content item (for example, the high-resolution version of a photo)
for the specified GUID.

Photos
RENDITION

DESCRIPTION

FORMAT

Main

A high-resolution version of the photo.

Note: For royalty-free images, the largest image size available is
returned.

JPEG

Preview

A low-resolution version of the photo (if available).

JPEG

Thumbnail A small version of the image (if available).

JPEG

Graphics
RENDITION

DESCRIPTION

FORMAT

Main

Source graphic.

A variety of formats (for example, JPEG,

PNG, Photoshop). To determine in which
formats a graphic is available, see Content
Item Formats and Filenames on page 28.

Preview

A low-resolution version of the graphic.

JPEG

Thumbnail A small version of the image.

JPEG

Video
RENDITION

DESCRIPTION

FORMAT

Main

A high-resolution version of the video

clip.

A variety of formats (for example,

Windows Media, Flash, MPEG-2, 3GP,
QuickTime), each at various quality levels.
To determine available formats, see
Content Item Formats and Filenames
on page 28.

Preview

A low-resolution version of the video clip.

Flash or Windows Media

An enlarged version of the image that

captures the first frame of the video clip.

JPEG

A small version of the image that captures

the first frame of the video clip.

JPEG

Thumbnail

Request
METHOD

REQUEST URI

GET

https://bapi.ap.org/{version}/item/{mediaType}/{id}/{rendition}?apiKey={apiKey}
&format={format}[&filename={filename}]

October 29, 2014

26

AP CONTENT API 2.8

Request URI Parameters

Required Parameters
PARAMETER

DESCRIPTION

VALID VALUES/EXAMPLES

version

The API version. Currently, the only valid value is v2.

v2

id

The GUID of a content item (not case-sensitive).

Any valid 32-character

GUID of a content item

rendition

The content item rendition.

Main, Preview or
Thumbnail

format

The format of the returned content item data. The format

can be specified either as one of the following:
The format MIME type in the request Accept header.
The format parameter value (takes precedence over the
Accept header value).
If no format is specified as the format parameter value or
in the Accept header, an error is returned. To determine
available formats, see Content Item Formats and
Filenames on page 28.

For AP Images

(required
only if the
Accept
header
value is not
specified)

content, including
GraphicsBank: jpeg,
png

For video: 3GPP, flv,

mp4, mpeg,
quicktime or
x-ms-wmv

Recommended Parameter
Important: It is strongly recommended to specify the mediaType parameter value in the item
rendition download links. The download links in search results always contain the media type.
PARAMETER

DESCRIPTION

VALID VALUES

mediaType

The content media type. The default for AP Images

(including all GraphicsBank content) is photo.

photo, graphic or video

Optional Parameter
PARAMETER

DESCRIPTION

VALID VALUES

filename

The filename for the downloaded content item rendition, in the format

See
Content
Item
Formats
and
Filenames
on page 28.

{ItemId}_{OriginalFilename}_{Width}x{Height}.{FileExtension}.

Important: For GraphicsBank, this parameter must be

specified to download each of the matte renditions of the
graphic. The filename parameter value for a matte rendition is

{ItemId}_{OriginalFilename}_{Width}x{Height}_matte.{File
Extension}. If the filename is not specified, the original (non-

matte) rendition of the graphic is returned. The download links

in search results always contain the filename.

Request Headers (Optional)

HEADER

DESCRIPTION

EXAMPLES

Accept

The MIME type of the returned

data format. To determine
available formats, see Content
Item Formats and Filenames on
page 28.

For AP Images content, including

GraphicsBank: image/jpeg, image/png
For video: video/3GPP, application/flv,
video/mp4, video/mpeg, video/quicktime
or video/x-ms-wmv

Accept-Encoding

Compresses the response to the

gzip format.

gzip

October 29, 2014

27

AP CONTENT API 2.8

Content Item Formats and Filenames

To retrieve various content item renditions, you can use either the MIME type or the format of the
content item located in the entrys <link> element in the search response. The filename that you can
use to save the content item rendition is also included in the entrys <link> element.

The MIME type of a content item rendition is located in the type attribute of the <link>
element (shown in green in the following example).

The format is located in value of the href attribute of the <link> element (shown in yellow in
the example).

The filename is located at the end of the href attribute value (shown in blue in the example).

- <entry>
<id>https://api.ap.org/v2/item/fedf6ff0f6564fc29449f189d9242349</id>

<title>Britain Mission Impossible Ghost Protocol</title>

<link rel="main" href="https://bapi.ap.org/v2/item/photo/fedf6ff0f6564fc29449f189d9242349/Main?format=jpeg

&filename=fedf6ff0f6564fc29449f189d9242349_Britain Mission Impossible Ghost Protocol
_3264x4896.jpg" type="image/jpeg" title="Full-Resolution (JPG)" />
<link rel="thumbnail" href="https://bapi.ap.org/v2/item/photo/fedf6ff0f6564fc29449f189d9242349/Thumbnail
?format=jpeg&filename=fedf6ff0f6564fc29449f189d9242349_Britain Mission Impossible Ghost Protocol
_85x128.jpg" type="image/jpeg" title="Thumbnail (JPG)" />
<link rel="preview" href="https://bapi.ap.org/v2/item/photo/fedf6ff0f6564fc29449f189d9242349/Preview
?format=jpeg&filename=fedf6ff0f6564fc29449f189d9242349_Britain Mission Impossible Ghost Protocol
_341x512.jpg" type="image/jpeg" title="Preview (JPG)" />

</entry>

Request URI Example

https://bapi.ap.org/v2/item/photo/fedf6ff0f6564fc29449f189d9242349/Main?format=jpeg&filename=fedf6f
f0f6564fc29449f189d9242349_Britain Mission Impossible Ghost Protocol_3264x4896.jpg&apiKey={apiKey}

Response
Returns the standard HTTP status code of 302 Found and redirects to the URL for the content
item binary. For information about error codes, see Error Codes on page 29.

October 29, 2014

28

AP CONTENT API 2.8

APPENDIX
ERROR CODES
In addition to the standard HTTP error codes, the error response includes an XML message in the
following format:
<?xml version="1.0" encoding="UTF-8"?>
<error>
<code>HTTP error code</code>
<message>Error message</message>
<!-- Optional information about the specific error condition --!>
</error>

XML message example:

<?xml version="1.0" encoding="UTF-8"?>
<error>
<code>404</code>
<message>The requested content item 74312a4943174baf114928ab0ec20b37 was not found</message>
<link rel="help" href="https://developer.ap.org/api-console" />
</error>

CODE

MESSAGE

ACTION

400

Specified parameter {ParameterName} is invalid

If the issue is not described in the

"Search and Metadata" section of the
AP Content API FAQs, check the
request syntax and parameters.

Specified value for {ParameterName}

{ParameterValue} is invalid
The request cannot be fulfilled due to bad syntax
Invalid API Key

Check the API key. If you have just

received your key, wait for a few hours
and try again. If you are still getting an
error, contact AP Customer Support at
[email protected].

You do not have permission to download this

content item

Refer to the "Downloads" section of the

AP Content API FAQs.

Over queries per minute limit

Over rate limit

Contact AP Customer Support at

[email protected].

404

The requested content item {itemID} was not

found

Refer to the "Downloads" section of the

AP Content API FAQs.

405

Request method {MethodName} not supported

Check the request method. Currently,

GET is the only supported HTTP
method for Content API requests.

413

The request is larger than the server is willing or

able to process

There are too many results; narrow

your search criteria.

414

URI length exceeds 6000 characters

Make sure that your request is no

longer than 6,000 characters.

500

Internal Server Error

502

Bad Gateway

503

Service Unavailable

504

Gateway Timeout

401

403

October 29, 2014

Contact AP Customer Support at

[email protected].

29

AP CONTENT API 2.8

TOP-LEVEL SUBJECT CATEGORIES

VALUE

ID (GUID)

Arts and entertainment

16cb0ba3e6d24d97ace39f5a1924669a

Business

c8e409f8858510048872ff2260dd383e

Environment and nature

8783d248894710048286ba0a2b2ca13e

Events

06a735407cb61004804eba7fa5283c3e

General news

f25af2d07e4e100484f5df092526b43e

Government and politics

86aad5207dac100488ecba7fa5283c3e

Health

cc7a76087e4e10048482df092526b43e

Lifestyle

3e37e4b87df7100483d5df092526b43e

Living things

6f072ea8b0064f3584c61e22f08836ee

Media

c188eb1088be10048dceb097165a0203

Obituaries

30c418e4b7644a9eb54409baf55036d1

Oddities

44811870882f10048079ae2ac3a6923e

Science

4bf76cb87df7100483dbdf092526b43e

Social affairs

75a42fd87df7100483eedf092526b43e

Sports

54df6c687df7100483dedf092526b43e

Technology

455ef2b87df7100483d8df092526b43e

October 29, 2014

30