Skip to content
Back to Home

Search and Feed

To learn about the differences between the Search and Feed methods, view typical workflows and try example requests, see Search or Feed? in Getting Started.

Searches content using the specified search criteria. Returns content item pricing information.

Search is used to query a database of existing content to find what you are interested in. To learn more, see Typical Search Workflow and Search Examples in Getting Started.

Request

  • Method: GET
  • Request URI (must be URL-encoded):

    https://api.ap.org/media/v[{version}]/content/search?apikey={apikey}[{optional_parameters}]

Base URI Parameter

  • version (optional). The API version; for example, 4 or 4.1. When this parameter value is not specified, the API version set as default for your account is returned. For more information, see API Versions.

Optional Parameters

Note

An implied AND operator is used between the parameters.

  • q. The query expression used to search for content. For more information, see Supported Query Syntax.

  • include, exclude. Parameters used to customize the fields returned in the response. For more information, see Customizing Response Fields.

  • text_links. Specifies the format of the text renditions (stories, captions, scripts and shotlists) to return in the response. For stories, the valid value is nitf (NITF) or anpa (ANPA 1312). For captions, scripts and shotlists, the valid value is nitf (NITF). The value of all returns all available formats (this is the default).

  • sort. The sort order of the returned results. By default, the results are sorted by relevance (meta.score) - the most relevant items first, regardless of the time period. Valid options are:

    • versioncreated:desc. The latest items first (reverse chronological order).
    • versioncreated:asc. The oldest items first (chronological order).
  • page_size. The maximum number of results to return per page. The default is 10 results with a maximum of 100 per page.

  • page. The requested page number within the set of search results. Page numbers start at 1.

    Note

    This parameter is not allowed on an initial query.

  • pricing. Specifying pricing=true in the request returns complete pricing information for each content item, including formatted price, use code and pricing message in addition to the price tags on renditions, which are returned by default. To learn more, see Pricing.

Request Header (Optional)

  • Accept-Encoding. Compresses the response to the gzip format. The valid value is gzip.

Request URI Examples

See Search Examples in Getting Started and Supported Query Syntax.

Response

The Search method returns the standard HTTP status code of "200 - OK" and search results in the JSON format.

Each result includes the content item ID, a requested set of metadata and links to all renditions of the content item (for example, thumbnail, preview and high-resolution versions of a picture). The response also includes complete pricing information for each content item if requested.

For information about error codes, see API Codes.

Response Headers

  • x-mediaapi-Q-name. The API method to which the throttle/quota applies (corresponds to the "method" property returned by Account Quotas. Possible values are search, feed, other.

  • x-mediaapi-Q-secondsLeft. The number of seconds remaining in the current period.

  • x-mediaapi-Q-used. Indicates the current usage and limit (the maximum number or calls allowed during the period), in the format {usage}/{limit}; for example, 1/6.

  • x-mediaapi-QDay-minutesLeft. (Optional; returned if a per-day quota is configured) The number of minutes remaining in the current period.

  • x-mediaapi-QDay-used. (Optional; returned if a per-day quota is configured) Indicates the current usage and limit (the maximum number or calls allowed during the period), in the format {usage}/{limit}; for example, 2/5000000.

Top-Level Properties

  • api_version. The API version.
  • api_mode. The API mode; for example, "live" or "preview."
  • id. The response ID.
  • method. The API method name and HTTP method.
  • params. Parameters used in the API request.
  • data. Contains the data and metadata associated with the response.

Response Descriptive Properties

  • query. The q parameter value used in the API request.
  • updated. The date and time (in UTC) when the response was generated.
  • total_items. The number of results available for the current search.
  • current_page. The current page number within the set of search results.
  • page_size. The number of search results returned per page. The default value is equal to the number of search results on the current page.
  • current_item_count. The number of search results on the current page.
  • next_page. A link to the next page of search results.
  • previous_page. A link to the previous page of search results.
  • page_template. A link template that can be used to navigate to any page of search results.
  • feed_href. A link to the feed on the last page of search results that allows you to transition from the search response to feed ingestion and monitor incoming content based on the same criteria as the original search.
  • items. Contains all of the items on this page.

Item Descriptive Properties

  • meta. Contains the non-content specific metadata for an item.

    • score. Search relevance score for this item.
    • products. Contains AP products or packages to which the content item belongs.
      • id. The product or package ID.
      • name. The product or package name.

    Note

    The "products" property is not returned by default. Use the include parameter to include this property in the response.

    • pricing. Pricing information for the content item (returned only when pricing=true is specified in the request). For more information, see Usage Instructions and Pricing.
  • item. Content-specific data and metadata for a content item. For more information, see Content Metadata Fields.

Sample Search Response

This example shows a response to the following request:

https://api.ap.org/media/v/content/search?q=Emma+Stone&apikey={apikey}&pricing=true&include=*

The pricing=true and include=* parameters are specified in this request to illustrate the "pricing" and "products" properties, which are not returned by default.

{
  "api_version": "4.1",
  "api_mode": "live",
  "id": "Hy3I1nqjZ",
  "method": "/content/search.GET",
  "params": {
    "include": [
      "*"
    ],
    "pricing": true,
    "q": "Emma Stone"
  },
  "data": {
    "query": "Emma Stone",
    "updated": "2017-09-28T17:20:20.160Z",
    "total_items": 3834,
    "current_page": 1,
    "page_size": 10,
    "current_item_count": 10,
    "next_page": "https://api.ap.org/media/v/content/search?page=2",
    "page_template": "https://api.ap.org/media/v/content/search?page={PAGE_NUMBER}",
    "items": [
      {
        "meta": {
          "score": 82.30266,
          "products": [
            {
              "id": 100024,
              "name": "AP Online"
            }
          ],
          "pricing": {
              // Human-readable pricing info
              "policy": {
                 // Machine-readable usage intructions and pricing
              }
           }
        },
        "item": {
          // Human-readable usage terms, content metadata and download links
        }
      }
    ]
  }
}

Feed

Note

If you are requesting feeds and have an unlimited subscription plan, pricing is typically not applicable.

Returns a feed of content matching the specified criteria. The returned feed items are sorted in chronological order, with the newest items at the bottom of the feed.

Feeds are used for content ingestion - monitoring a stream of content to receive all updates and new content going forward. To learn more, see Typical Feed Workflow and Feed Examples in Getting Started.

About Long Polling

For efficiency on feed requests, the AP Media API server uses HTTP long polling where the server holds the client's feed request open until new content becomes available or up to 15 seconds. If there is new content when your client application makes the feed request, this content is immediately returned. Otherwise, the content is returned as soon as it becomes available during the next 15 seconds. An empty response is returned only if no new content is available after 15 seconds, which helps minimize the number of empty responses and improves efficiency.

Request

  • Method: GET
  • Request URI (must be URL-encoded):

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

Base URI Parameter

  • version (optional). The API version; for example, 4 or 4.1. When this parameter value is not specified, the API version set as default for your account is returned.

Optional Parameters

Note

An implied AND operator is used between the parameters.

  • q. The query expression used to filter content. For more information, see Supported Query Syntax.

  • include, exclude. Parameters used to customize the fields returned in the response. For more information, see Customizing Response Fields.

  • text_links. Specifies the format of the text renditions (stories, captions, scripts and shotlists) to return in the response. For stories, the valid value is nitf (NITF) or anpa (ANPA 1312). For captions, scripts and shotlists, the valid value is nitf (NITF). The value of all returns all available formats (this is the default).

  • page_size. The maximum number of items to return per page. The default is 10 items with a maximum of 100 per page.

  • versions. Specifies whether to return all available versions of the content item and all ANPA filings or only the latest (the same story in the ANPA format may be filed multiple times; for example, with a different category code):

    • By default or if versions=latest is specified in the request, only the latest version of the content item and the latest filing of the ANPA story is returned.
    • When versions=all is specified in the request, the API returns all filings of ANPA-formatted stories and multiple versions of a content item (if available) rather than only the latest version. For ANPA-formatted stories, the response includes links to all filings in renditions.anpa.version_links.

Request Header (Optional)

  • Accept-Encoding. Compresses the response to the gzip format. The valid value is gzip.

Request URI Examples

See Feed Examples in Getting Started and Supported Query Syntax.

Response

The Feed method returns the standard HTTP status code of "200 - OK" and a feed of content in the JSON format.

Each feed entry includes the content item ID, a requested set of metadata and links to all renditions of the content item (for example, thumbnail, preview and high-resolution versions of a picture).

For information about error codes, see API Codes.

Response Headers

  • x-mediaapi-Q-name. The API method to which the throttle/quota applies (corresponds to the "method" property returned by Account Quotas. Possible values are search, feed, other.

  • x-mediaapi-Q-secondsLeft. The number of seconds remaining in the current period.

  • x-mediaapi-Q-used. Indicates the current usage and limit (the maximum number or calls allowed during the period), in the format {usage}/{limit}; for example, 1/6.

  • x-mediaapi-QDay-minutesLeft. (Optional; returned if a per-day quota is configured) The number of minutes remaining in the current period.

  • x-mediaapi-QDay-used. (Optional; returned if a per-day quota is configured) Indicates the current usage and limit (the maximum number or calls allowed during the period), in the format {usage}/{limit}; for example, 2/5000000.

Top-Level Properties

  • api_version. The API version.
  • api_mode. The API mode; for example, "live" or "preview."
  • id. The response ID.
  • method. The API method name and HTTP method.
  • params. Parameters used in the API request.
  • data. Contains the data and metadata associated with the response.

Response Descriptive Properties

  • query. The q parameter value used in the API request.
  • updated. The date and time (in UTC) when the response was generated.
  • current_item_count. The number of items on the current page.
  • next_page. A link to the next page of the feed.

    Tip

    To check for any updates since your previous request, it is strongly recommended that your client application use the "next_page" link returned in the feed response for the next request. For more information, see Using Next Request Links for Content Updates.

  • items. Contains all of the items on this page.

Item Descriptive Properties

  • meta. Contains the non-content specific metadata for an item.

    • products. Contains AP products or packages to which the content item belongs.
      • id. The product or package ID.
      • name. The product or package name.
    • followedtopics. Contains AP Newsroom Followed Topics to which the content item belongs.
      • id. The Followed Topic ID.
      • name. The Followed Topic name.

    Note

    The "products" and "followedtopics" properties are not returned by default. Use the include parameter to include these properties in the response.

  • item. Content-specific data and metadata for a content item. For more information, see Content Metadata Fields.

Sample Feed Response

This example shows a response to the following request:

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

The include=* parameter is specified in this request to illustrate the "products" and "followedtopics" properties, which are not returned by default.

{
  "api_version": "4.1",
  "api_mode": "live",
  "id": "r10Q829oZ",
  "method": "/content/feed.GET",
  "params": {
    "include": [
      "*"
    ],
    "q": "prodictid:31989",
  },
  "data": {
    "query": "prodictid:31989",
    "updated": "2017-09-28T17:49:26.752Z",
    "page_size": 10,
    "current_item_count": 10,
    "next_page": "https://api.ap.org/media/v/content/feed?q=prodictid:31989&seq=217647413",
    "items": [
      {
        "meta": {
          "products": [
            {
              "id": 31989,
              "name": "AP Online Top General Headlines"
            }
          ],
          "followedtopics": [
            // AP Newsroom Followed Topics to which the content item belongs
          ]
        },
        "item": {
          // Human-readable usage terms, content metadata and download links
        }
      }
    ]
  }
}

Supported Query Syntax

Note

This section applies only to specifying the query expression (the value of the q parameter in search and feed 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".

Fielded Query

  • Use ':' instead of '='; for example:

    slug:travel

    headline:storm

  • To include more than one keyword in a field, enclose the keywords in parentheses ( ) or straight quotes " "; for example:

    slug:(football OR nfl) finds either football or nfl in the slug.

    headline:(phelps AND olympics) finds both phelps and olympics in the headline.

    title:"Michael Phelps" finds the full name Michael Phelps in the title.

    Tip

    When specifying multiple possible values for the same field, make sure to include your desired Boolean operator. For example, use type:(text OR picture) instead of type:(text picture).

For more information, see Common Query Fields.

Boolean Operators (AND/OR/NOT)

  • Use AND to find results with all of your keywords in the same content item. Use OR to find results with either of your keywords in the same content item. Use NOT to exclude a keyword. AND, OR and NOT must be uppercase; for example:

    tennis AND Williams

    raptors AND NOT category:s

    Istanbul OR Izmir OR Ankara

Exact Phrases

  • Use straight quotes " " to find results with an exact phrase or name; for example:

    "Michael Phelps"

    "climate change"

Grouping Terms

  • Group parts of your query with parentheses ( ); for example:

    ("Prince George" OR pgc) AND (Maryland OR md)

    title:(Illinois AND governor)

Position Operator

  • In fielded queries, search for terms near one another using "~"; for example:

    headline:"tennis Williams"~5 finds the terms tennis and Williams within five words of each other in the headline.

Wildcard Operators

  • Use '*' to replace zero or more characters at the end of a word; use '?' to replace one character.

    Fre* finds Fred, Freddy, Freddie, etc.

    Gr?y finds Gray or Grey.

Common Query Fields

  • byline (returned in bylines). Name of the writer, photographer, editor or producer to whom the content item is attributed; for example:

    byline:"ben liebenerg"

    byline:"don babwin"

  • editorialtype (returned in editorialtypes). The editorial condition of the story, such as Advance, HoldForRelease or Lead; for example:

    editorialtype:correction

    editorialtype:add

  • photographer (returned in photographer). Name of the photographer who created the image; for example:

    photographer:"ivan sekretarev"

  • category (returned in subject.rels:category). The name, one-letter or three-letter category code of the content item's subject, such as domestic news or entertainment; for example:

    category:a

    category:spx

    category:sports

    For a list of possible values, see AP Category Codes and AP Supplemental Categories.

  • editorialpriority (returned in editorialpriority). The one-letter AP priority code that represents the urgency of a story; for example:

    editorialpriority:u

    editorialpriority:b

    For a list of possible values, see editorialpriority in Urgency.

  • format (returned in textformat). Two-letter filing format code indicating the type of text set, such as agate; for example:

    format:bx

    format:at

  • fixture (returned in fixture). Named sets of regularly occurring content or features with a predictable focus, such as Today in History or On the Money; for example:

    fixture:"today in history"

    fixture:techbits

    For a list of possible values, see Fixture.

  • company (returned in organisation). The name or ticker symbol of a publicly-traded company; for example:

    company:apple

    company:goog

  • industry, industryname (returned in organisation.industries). Categories describing the principal product or service of a manufacturing service organization, such as the Energy industry; for example:

    industry:"online retail"

    For possible values, use CTRL-F to search for "industry" on the AP Subject page.

    Tip

    Searching by code is a better guarantee of uniqueness; for example, industry:6fd7e1aa975ef14a80f93a1da7d78c3a finds content tagged with "Information technology".

  • instrument (returned in organisation.symbols.instrument). The combination of a company's ticker symbol and the stock exchange on which the company is traded in the format <stock exchange code>:<ticker symbol>; for example:

    instrument:"nasdaq:goog"

    Tip

    As tickers are not unique across stock exchanges, searching by instrument is a better guarantee of uniqueness.

    For a list of stock exchange codes, see Stock Exchange Codes.

  • itemcontenttype, contenttype (returned in profile). The type of information contained in the content item. Currently, content types are applied to text and audio news items; for example:

    contenttype:"press release"

    itemcontenttype:newsbrief

    For a list of possible values, see Profile (ItemContentType).

  • ticker (returned in organisation.symbols.ticker). A company's ticker symbol; for example:

    ticker:msft

    Tip

    As tickers are not unique across stock exchanges, searching by instrument is a better guarantee of uniqueness.

  • located, dateline (returned in located). The date and/or place where the news took place; for example:

    located:brazil

    dateline:seattle

  • city (returned in datelinelocation:city). The name of the city where the content item was created; for example:

    city:paris

    city:"new orleans"

  • state (returned in datelinelocation:countryareaname and datelinelocation:countryareacode). The name or postal code of the state where the content item was created; for example:

    state:OH

    state:"new mexico"

  • country (returned in datelinelocation:countryname and datelinelocation:countrycode). The name or three-letter code of the country where the content item was created; for example:

    country:canada

    country:aus

  • geography, geo (returned in place). Any geographic location (city, state, country, continent, etc.) that the content item is about or where it took place. Using this field returns content to which the geography is automatically applied. Examples:

    geography:europe

    geo:tokyo

    For a list of possible values, see AP Geography.

    Tip

    Searching by code is a better guarantee of uniqueness; for example: geography:661850e07d5b100481f4c076b8e3055c.

  • location, place (returned in located, datelinelocation and/or place). An aggregate of all location-related fields; using this field searches simultaneously in dateline, city, state, country, geography, etc. Examples:

    place:california

    location:berlin

  • slug, slugline (returned in slugline). The story type identifier; used in sluglines for news items; for example:

    slug:fea

    slugline:obit

  • transref (returned in altids.transref). Transmission Reference Number; the alphanumeric identifier (or file name) associated with a story or picture; for example:

    transref:j2448

  • headline. The content item's headline; a list of keywords to aid in the search for the item; for example:

    headline:(russia AND putin)

    headline:("tom brady" AND superbowl)

  • organization (returned in organisation). Names of organizations or groups (other than companies), such as government departments and national Olympic teams; for example:

    organization:"new york giants"

    organization:"world health organization"

    For a list of possible values, see AP Organization.

    Tip

    Searching by code is a better guarantee of uniqueness; for example, organization:1b1ee09884971004870e91f43387513e finds content tagged with "National Football League".

  • person (returned in person). In pictures, the name of a person in the news drawn from a list of celebrities, politicians, sports figures, business leaders and other newsmakers. This person may be mentioned in the caption and tagged by classification, but is not necessarily pictured. Example:

    person:"kate middleton"

    Tip

    To search for images where the person is pictured, include persons.rels:personfeatured in your query (see next).

  • person AND persons.rels:personfeatured. In pictures, the name of a person who is actually pictured in the image; for example:

    (person:"michael phelps" AND persons.rels:personfeatured)

  • source (returned in infosource). The organization that created the content item; for example:

    source:ap

    source:"philadelphia inquirer"

  • subject (returned in subject). The subject word, phrase or code used to search for content items by a concept; for example:

    subject:"california wildfires"

    subject:celebrity

    For a list of possible values, see AP Subject.

    Tip

    If you are looking for a specific AP Subject, searching by code is a better guarantee of uniqueness; for example, subject:c946c3908b6b10048d99a385cd5ce603 finds content tagged with "Consumer electronics'.

  • suppcat, supcat (returned in subject.rels:suppcategory). The content item's 3- or 4- letter supplemental (or secondary) news classification category; for example:

    supcat:BKB"

    suppcat:ENT

    For a list of possible values, see AP Supplemental Categories.

  • title (returned in title). The content item's title; generally used for pictures; for example:

    title:"World Cup"

    title:(new york fashion show)

  • language (returned in language). The two-letter code of the language that the content item is written in; for example:

    language:en

    language:es

  • versioncreated (returned in versioncreated). The date when this version of the content item was published. Use square brackets [min TO max] to specify inclusive ranges and curly brackets {min TO max} to specify exclusive ranges; for example:

    versioncreated:[2015-11-12 TO *]

    versioncreated:[2015-10-31 TO 2015-10-31]

    versioncreated:<now-3d (arrived later than three days ago)

    versioncreated:{now-2d TO now-1d}

  • firstcreated (returned in firstcreated). The date when the first version of the content item was created; for example:

    firstcreated:[2016-05-15 TO 2016-05-18]

  • event (returned in subject; may be returned in event for some sports events such as NFL and for developing news events such as The Latest). The name of an event that the content item describes; for example:

    event:olympics

    For possible values, use CTRL-F to search for "event" on the AP Subject page.

    Tip

    Searching by code is a better guarantee of uniqueness; for example, subject:47a2f6181cff4d379227f49015d1a187 finds content tagged with "2018 Pyeongchang Olympic Games".

  • sourcetype (returned in infosource.type). The type of source that created the content item; for example:

    sourcetype:thirdparty

    sourcetype:member

  • productid (returned in meta.products.id). One or more AP product or package IDs; for example:

    productid:30079

    productid:(30079+OR+31536)

  • followedtopicid (returned in meta.followedtopics.id). One or more AP Newsroom Followed Topic IDs; for example:

    followedtopicid:700764

    followedtopicid:(701285+OR+700763)

Customizing Response Fields

Required vs. Default Fields

API responses always include certain metadata fields when available and applicable. Attempting to exclude these fields from responses results in an error.

These required fields are marked as ("May not be excluded") in Content Metadata Field Definitions. In addition to the required fields, the API returns a default set of fields in the search and feed responses.

All available fields are returned by default in the item metadata, account plans and account download history responses.

Including and Excluding Fields

You can use one or more of the following parameters to customize the returned fields:

  • include. One or more comma-separated fields to include in the response in addition to the required fields (NOT in addition to the default fields); for example, include=signals or include=subject,place,organisation,person.

    • include=* returns all available fields.

    • include=view_default,<field_name> returns the default fields plus your own list; for example:

      include=view_default,subject returns the default fields plus subject

    • include=*.<field_name> returns every field with a specific attribute; for example:

      include=*.title returns photographer.title, renditions.main.title, renditions.preview.title and renditions.thumbnail.title for pictures

    • include=<field_path> returns a specific field; for example:

      subject.code or renditions.thumbnail.href

    • Using * to replace characters in the field name (for example, include=description_*) is NOT supported.

    • On the individual item metadata request, you can reference include=view_default_searchDisplay to get the default fields returned by the Search method; for example, when just updating a previous search result.

  • exclude. One or more comma-separated fields to exclude from the set of fields specified by the include parameter (or from a default set of fields if no include parameter is specified); for example, exclude=datelinelocation.

    • exclude=* excludes every content item metadata field except the required fields and those specified in the value of the include parameter; for example:

      include=renditions.main,datelinelocation,subject&exclude=* excludes all fields except the fields that may not be excluded and renditions.main, datelinelocation and subject.

    • exclude=*.<name> excludes every field with a specific attribute; for example:

      exclude=*.code excludes all fields with the code attribute

    • exclude=<field_path> excludes a specific field; for example, subject.code or renditions.main.originalfilename.

    • Using * to replace characters in the field name (for example, exclude=description_*) is NOT supported.

Usage Instructions and Pricing

Human-Readable Messages

Use Information and Special Instructions

Important

Always check the following fields for any human-readable rights information, usage limitations, special restrictions and editorial notes: usageterms, renditions.script_[format], renditions.shotlist_[format] and ednote.

  • usageterms. Use information and special restrictions:

    • Use information; for example, "This content is intended for editorial use only. For other uses, additional clearances may be required."

    • Special restrictions (if any); for example: "No Use in Japan", "No Archiving Permitted" or "AP Clients Only."

  • ednote. Editorial instructions for processing the item. Do not distribute this information to news consumers.

  • renditions.script_[format] and renditions.shotlist_[format]. Special restrictions included in the video script and/or shotlist.

Item Price, Use Code and Pricing Message

If pricing=true is specified in the request, the API returns the following in the meta property adjacent to the item to which the pricing applies:

  • The content item price:

    • pricing.amount. The charge for the content item.
    • pricing.currency. The currency of the charge; in one of the following:

      • Actual currency; for example, US dollars.
      • Meter ticks, which is a form of virtual currency for content items included in your plan. For example, if your plan allows for a certain number of downloads per billing cycle, the charge for the content item in meter ticks indicates how many download units are deducted from your meter once the content item is downloaded.
    • pricing.formatted. The formatted price that may be used for display; for example, on a website.

    • pricing.tier. (For plans such as Choice) The name of the Choice tier used by your plan's meter to calculate the payment amount.
  • Use code and pricing message. A use code in the pricing.apusecode property and a pricing message in the pricing.message property:

    Pricing Scenario Use Code Plan Type API Pricing Message
    Included in Your Plan 810 Choice Included in your Choice plan at the Tier indicated
    801 Other plans Included in your plan
    Not Included in Your Plan (Extra Charge) 851 All plans Not included in your plan. Available for an extra charge.
    Not Included in Your Plan (Contact Licensing) 860 All plans Not included in your plan. To learn more about license rights, please contact your licensing representative.

Example: Pricing for an Item Included in Your Plan
"pricing": {
   "amount": 1,
   "currency": "Meter Ticks",
   "formatted": "1 Meter Tick",
   "apusecode": 801,
   "message": "Included in your plan."
}
Example: Pricing for an Item Available for an Extra Charge
"pricing": {
   "amount": 42,
   "currency": "USD",
   "formatted": "$42.00",
   "apusecode": 851,
   "tier": "Tier 1 - PhotoChoice",
   "message": "Not included in your plan. Available for an extra charge."
}

Example: Image Use Instructions and Pricing

This picture search result example shows human-readable pricing information in pricing, editorial notes in ednote, and use information and special restrictions in usageterms:

"meta": {
  ...
  "pricing": {
  "amount": 30,
  "currency": "USD",
  "formatted": "$30.00",
  "apusecode": 851,
  "message": "Not included in your plan. Available for an extra charge."
   ...
  },
  "item": {
    "uri": "https://api.ap.org/media/v/content/31b80a551a5345ae813c0f1b9bf348e2",
    "altids": {
      "itemid": "31b80a551a5345ae813c0f1b9bf348e2",
       ...
    },
     ... 
    "type": "picture", 
     ...
    "ednote": "JAPAN OUT, CREDIT MANDATORY",
     ...
    "headline": "JAPAN SCHOOL SCANDAL ABE",
     ...
    "usageterms": [
      "This content is intended for editorial use only. For other uses, additional clearances may be required.",
      "No Use in Japan",   
    ],
  }
}

Example: Video Use Instructions and Pricing

This video search result example shows human-readable pricing information in pricing, use information and usage limitations in usageterms, and additional special restrictions included in the video script, which is returned in the NITF format when you follow the link in renditions.script_nitf.href.

"meta": {
  ...
  "pricing": {
    "amount": 1,
    "currency": "Meter Ticks",
    "formatted": "1 Meter Tick",
    "apusecode": 801,
    "message": "Included in your plan.",
     ...
  },
  "item": {
    "uri": "https://api.ap.org/media/v/content/2e03ef1f9eb10555b8c2100bd3017186",
    "altids": {
      "itemid": "2e03ef1f9eb10555b8c2100bd3017186",
       ...
    },
     ...
    "type": "video",
     ...
    "headline": "Multi camera footage from the TOMMYNOW show in London, featuring performance by The Chainsmokers",
     ...
    "usageterms": [
      "This content is intended for editorial use only. For other uses, additional clearances may be required.",
      "International: AP Clients Only | US: AP Clients Only"
    ],
     ...
    "script_nitf": {
      "title": "NITF Script Download",
      "rel": "Script",
      "format": "IIM",
      "mimetype": "text/xml",
      "fileextension": "xml",
      "words": 406,
      "contentid": "f33aae2c988543d0b4ce2ab766f1d114",
      "href": "https://api.ap.org/media/v/content/2e03ef1f9eb10555b8c2100bd3017186/download?type=text&format=nitf&text=script"
    }
  }
}

In this example of the Script rendition, the special restrictions appear in the RESTRICTION SUMMARY:

<nitf version="-//IPTC//DTD NITF 3.4//EN" change.date="October 18, 2006" change.time="19:30">
  <body>
    <body.content>
      <block id="Script">
        <p></p>
        <p>SHOTLIST:</p>
        <p>RESTRICTION SUMMARY:</p>
        <p>CLIENTS PLEASE NOTE: THE MUSIC USED IN THIS RUNWAY SHOW HAS NOT BEEN CLEARED FOR USE. WE RECOMMEND YOU REPLACE IT WITH YOUR OWN CLEARED MUSIC</p>
        <p>TOMMYNOW</p>
        <p>London, 19 September 2017</p>
        <p>++ SHOTS 1-5 ARE MUTE AT SOURCE++</p>
        <p>1. Medium of Tommy Hilfiger</p>
           ...
        <p>5. Various of Gigi Hadid and Tommy Hilfiger posing with models</p>
           ...
        <p>8. Various of performance by the Chainsmokers</p>
        <p>STORYLINE: </p>
        <p>MULTI CAMERA FOOTAGE OF THE TOMMYNOW SHOW IN LONDON, FEATURING PERFORMANCE BY THE CHAINSMOKERS</p>
        <p>Designer Tommy Hilfiger and model Gigi Hadid staged a grungy rock affair for their show on the final night of London Fashion Week.</p>
        <p>It was the pair's third collaboration and featured appearances by Hadid's siblings, Bella and Anwar.</p>
           ...
        <p>American electro act The Chainsmokers performed at the conclusion of the show.</p>
      </block>
    </body.content>
  </body>
</nitf>

Machine-Readable Instructions

Format

Content API returns machine-readable usage instructions and pricing as a JSON representation of RightsML, which is based on ODRL.

ODRL Elements

If pricing=true is specified in the request, the following ODRL elements are returned for each content item:

Top-Level Properties
  • policy. The ODRL Policy, which specifies the permitted or prohibited Actions that may be performed on the specified Assets.
    • policytype. The Policy type that determines how the policy is to be interpreted. "Set" is currently the only supported value.
    • policyid. The unique Policy identifier.
    • "permissions" OR "prohibitions". A Permission allows a certain Action to be performed on a specified Asset (for example, download and use the content item). A Prohibition forbids the action.
Permission/Prohibition Descriptive Properties
  • target. The content item ID to which the Permission or Prohibition applies.
  • action. Indicates permitted or prohibited usage.
  • assigner. The URL to the assigner's website.
  • constraints. Indicates limitations to the permitted usage; for example, "editorial use only."

    • name. Specifies the type of constraint, such as "purpose."
    • operator. Specifies how to evaluate the constraint; for example, "equal to."
    • rightoperand. The value required to meet the constraint; for example, "editorial use only."
  • duties. Expresses a Duty that must be satisfied in order to exercise the Permission.

Duty Descriptive Properties
  • action. Identifies the specific action that must be performed to carry out the Duty; for example, "compensate" (pay a certain amount) or "reviewPolicy" (refer to usage terms).

    Note

    If there are no special restrictions in usageterms, the duty to review policy will not be returned.

  • constraints. Indicates a condition of the Duty; for example, that a specific amount must be paid.

    • name. Specifies the type of constraint, such as "the amount to pay."
    • operator. Specifies how to evaluate the constraint; for example, "equal to."
    • rightoperand. The value required to meet the constraint; for example, the charge amount.
    • rightoperanddatatype. The XML schema data type of the "right operand" value; for example, "decimal."
    • rightoperandunit. The unit used in expressing the "right operand" value; for example, the currency of the charge.

Examples

The following examples show the machine-readable use and pricing information returned by the API for each of the pricing scenarios.

Note

These examples assume that special restrictions for the sample content item (for example, "No Use in Japan") are returned in usageterms. For content items with no special restrictions, the duty to review policy will not appear in the machine-readable instructions.

Included In Your Plan (Choice)

In this example:

  • Lines 4-6 indicate a permission to download and use the specified content item (included in your Choice plan).

  • Lines 12, 15 and 17 indicate the Choice tier that will be used by your plan's meter to calculate the payment amount.

  • Lines 12 and 21 indicate that you must review the human-readable special restrictions in the usage terms.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
"policy": {
  "policytype": "https://www.w3.org/ns/odrl/2/Set",
  "policyid": "https://api.ap.org/policies/6aef5ea3533922f726a1f12dd7dff406",
  "permissions": [{
    "target": "https://api.ap.org/media/v/content/fedf6ff0f6564fc29449f189d9242349",
    "action": "https://www.w3.org/ns/odrl/2/use",
    "assigner": "http://ap.org/",
    "constraints": [{
      "name": "https://www.w3.org/ns/odrl/2/purpose",
      "operator": "https://www.w3.org/ns/odrl/2/eq",
      "rightoperand": "http://cv.ap.org/odrl/purpose/editorial"}],
    "duties": [{
      "action": "https://www.w3.org/ns/odrl/2/compensate",
      "constraints": [{
        "name": "https://www.w3.org/ns/odrl/2/payAmount",
        "operator": "https://www.w3.org/ns/odrl/2/eq",
        "rightoperand": "http://cv.ap.org/odrl/plantypes/Tier/3",
        "rightoperanddatatype": "https://www.w3.org/2001/XMLSchema:anyURI",
        "rightoperandunit": "http://cv.ap.org/odrl/units/plantype"}]},
     {
      "action": "https://www.w3.org/ns/odrl/2/reviewPolicy"}]}]}
Included In Your Plan (Other Plans)

In this example:

  • Lines 4-6 indicate a permission to download and use the specified content item included in your plan (this download will be deducted from the number of available downloads).

  • Lines 12 and 13 indicate that you must review the human-readable special restrictions in the usage terms.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
"policy": {
  "policytype": "https://www.w3.org/ns/odrl/2/Set",
  "policyid": "https://api.ap.org/policies/3922f726a1f12dd7dff4066aef5ea353",
  "permissions": [{
    "target": "https://api.ap.org/media/v/content/fedf6ff0f6564fc29449f189d9242349",
    "action": "https://www.w3.org/ns/odrl/2/use",
    "assigner": "http://ap.org/",
    "constraints": [{
      "name": "https://www.w3.org/ns/odrl/2/purpose",
      "operator": "https://www.w3.org/ns/odrl/2/eq",
      "rightoperand": "http://cv.ap.org/odrl/purpose/editorial"}],
    "duties": [{
      "action": "https://www.w3.org/ns/odrl/2/reviewPolicy"}]}]}
Not Included In Your Plan (Extra Charge, All Plans)

In this example:

  • Lines 4-6 indicate a permission to download and use the specified content item once the extra charge amount is paid.

  • Lines 12, 15, 17 and 19 indicate the extra charge amount that will be paid in the specified currency. For currency values, refer to ISO 4217.

  • Lines 12 and 21 indicate that you must review the human-readable special restrictions in the usage terms.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
"policy": {
  "policytype": "https://www.w3.org/ns/odrl/2/Set",
  "policyid": "https://api.ap.org/policies/6aef5ea3533922f726a1f12dd7dff406",
  "permissions": [{
    "target": "https://api.ap.org/media/v/content/fedf6ff0f6564fc29449f189d9242349",
    "action": "https://www.w3.org/ns/odrl/2/use",
    "assigner": "http://ap.org/",
    "constraints": [{
      "name": "https://www.w3.org/ns/odrl/2/purpose",
      "operator": "https://www.w3.org/ns/odrl/2/eq",
      "rightoperand": "http://cv.ap.org/odrl/purpose/editorial"}],
    "duties": [{
      "action": "https://www.w3.org/ns/odrl/2/compensate",
      "constraints": [{
        "name": "https://www.w3.org/ns/odrl/2/payAmount",
        "operator": "https://www.w3.org/ns/odrl/2/eq",
        "rightoperand": "20.00",
        "rightoperanddatatype": "https://www.w3.org/2001/XMLSchema#decimal",
        "rightoperandunit": "http://cvx.iptc.org/iso4217a/USD"}]},
     {
      "action": "https://www.w3.org/ns/odrl/2/reviewPolicy"}]}]}
Not Included In Your Plan (Contact Licensing, All Plans)

In this example, lines 4-6 indicate that you are prohibited from downloading or using the specified content item. It is not included in your plan; you can contact your licensing representative to learn more about license rights.

Note

When a content item is not available for download, the search, feed and item metadata responses do not include the download links to the high-resolution rendition of the content item. Only the links to the preview and thumbnail renditions are included. You may NOT use the preview or thumbnail renditions of browse-only content.

1
2
3
4
5
6
7
"policy": {
  "policytype": "https://www.w3.org/ns/odrl/2/Set",
  "policyid": "https://api.ap.org/policies/dd7dff46aef5ea3533922f726a1f1206",
  "prohibitions": [{
    "target": "https://api.ap.org/media/v/content/fedf6ff0f6564fc29449f189d9242349",
    "action": "https://www.w3.org/ns/odrl/2/use",
    "assigner": "http://ap.org/"}]}