Skip to content

Content Metadata Fields

Tip

AP content metadata helps you search or group content in your own systems, from routing content into your CMS buckets using AP category codes to automatically populating photo galleries by identifying images with topical subjects; for example, 'Celebrity' and 'Natural disasters'. AP classification metadata is designed to help you get the most out of the content delivered by the AP. Learn more >>

These content-specific data and metadata fields may be returned for a content item by the API or included in the JSON metadata files downloaded by the agent. The content item metadata is available in the JSON item property.

Note

  • Using the agent? The downloaded JSON metadata files include all metadata fields if applicable and available.
  • Accessing the API directly? Content item metadata is returned in the Search, Feed or Content Item response. In the descriptions below:
    • (API: May not be excluded) indicates fields that cannot be excluded from the responses using the exclude parameter (these fields are always returned by default if available).
    • (API: Default) indicates fields that are returned by default when no include and/or exclude parameters are specified.

uri

(API: May not be excluded) The identifier for this content item expressed as a URI.

{// Example:
 "uri": "https://api.ap.org/media/v/content/efe60501a36428b35cd2ffe38e3e4568"}

altids

(API: May not be excluded) Alternative IDs of a content item:

  • itemid (API: May not be excluded). A unique ID that remains the same throughout all revisions of the content item. For example, if a news story is written and rewritten several times as new information is uncovered, this ID value remains the same for each rewrite because it points to the chain of revised stories, and not an individual version. To learn more, see Managing Revisions and Duplicates.

  • etag (API: May not be excluded). A unique token for each revision of a content item, which helps detect duplicates. To learn more, see Managing Revisions and Duplicates.

  • friendlykey (API: May not be excluded). A human-readable ID of a content item, typically used for images. For video, videoid (see below) is typically used as a human-readable ID.

  • videoid. A human-readable video ID (also known as story ID or AP Archive story number).

  • transref. Transmission Reference Number; the alphanumeric identifier (or file name) associated with a story, picture or video.

{// Example: Picture altids
 "altids": {
   "itemid": "169bf4e1ed114d849bb4bc30b9377929",
   "etag": "169bf4e1ed114d849bb4bc30b9377929_0a1aza3c89898",
   "friendlykey": "18092593065168",
   "transref": "MIARB106"}
{// Example: Video altids
 "altids": {
   "itemid": "efe60501a36428b35cd2ffe38e3e4568",
   "etag": "efe60501a36428b35cd2ffe38e3e4568_0a9aza8c88353",
   "friendlykey": "8946104261",
   "videoid": "nz004659",
   "transref": "vt7426"}

foreignkeys

May contain one of the following:

  • Third-party keys submitted to the AP by content providers; for example:

    memberentryid and membermanagementid. IDs submitted in an ATOM feed that meets AP specifications. For information about other news management values that you submitted in the ATOM feed, see Migration Guide for AP WebFeeds Users.

    {// Example:
     "foreignkeys": {
       "memberentryid": "urn:publicid:localnewspaper.com:a1234b5678",
       "membermanagementid": "urn:publicid:localnewspaper.com:c9012d3456"}}
    
  • A human-readable story ID for audio and video (for video, this ID is the same as returned in altids.videoid).

    {// Example:
     "foreignkeys": {
        "storyid": "apa009966"}}
    

version

(API: Default) The content item version number: 0 for the initial version, 1 for the first version, 2 for the second version and so on. The higher the number, the more recent the content item's version.

  • For text stories, this is the version of the story revision.
  • For other media types (for example, pictures, graphics and video), this is the version of the item metadata; for example, an image caption. Typically, significant changes to the binary asset (such as a picture) are published as a new content item.

To learn more, see Managing Revisions and Duplicates.

{// Example:
"version": 0}

type

(API: Default) The generic news type of this content item: text, picture, graphic, audio or video.

{// Example:
"type": "video"}

urgency

The editorial urgency of the content from 1 to 8. 1 represents the highest urgency, 8 the lowest.

{// Example:
"urgency": 4}

editorialpriority

The one-letter AP priority code that represents the urgency of a story; for example, f, u or r. Because usage is deprecated, systems must rely on the urgency value for processing. For information about the mapping of the urgency and editorialpriority values, see Urgency.

{// Example:
"editorialpriority": "r"}

profile

The type of information contained in the news item (also known as 'Item Content Type'); for example, Spot Development, Advisory and Weather Forecast. Currently, content types are applied to text and audio news items. For a complete list of values, see Profile (ItemContentType).

Tip

You can use this field to identify whether and how to display the content; for example, the value of "Advisory" distinguishes advisories from content that may be published to consumers. You can also include or exclude content in product groups or automated processes based on the content type. Learn more >>

{// Example:
"profile": "Press Release"}

language

The two-letter code of the language that the news item is written in; for example, en or es.

Tip

This field helps select content by language; for example, filter out content written in languages other than English.

{// Example:
"language": "de"}

versioncreated

(API: Default) The date and time when this version of the content item was published.

{// Example:
"versioncreated": "2017-11-15T21:35:17Z"}

firstcreated

(API: Default) The date and time when the first version of the item was created.

  • For pictures and video, this is the date and time when the content for the item was created. For example, a picture taken at a Sunday night game and published on Monday morning would carry the firstcreated value from Sunday, and the versioncreated value for the picture entry would be from Monday.

  • For GraphicsBank items, this is the date of the news event that the graphic illustrates.

Note

For news items with multiple revisions, such as news stories, the firstcreated value is the date and time when the current (not the first) version was filed.

{// Example:
"firstcreated": "2017-11-15T21:25:39Z"}

embargoed

(API: May not be excluded) The date and time before which all versions of the content item are embargoed (if absent, this item is not embargoed).

Important

To determine whether an item is embargoed, make sure to check the embargoed value. Do not distribute an embargoed content item to news consumers until the release date-time found in embargoed has occurred. To learn more, see Identifying Publishable Content.

{// Example:
"embargoed": "2017-11-15T21:25:39Z"}

pubstatus

(API: May not be excluded) The publishing status of the content item, which contains information regarding the item's ability to be distributed to news consumers. This value is usable by default.

  • usable. This content item may be distributed to news consumers in publishing forms that do not violate your agreement with the AP and copyright information contained in the content item and its metadata.

  • embargoed (the same as Hold-For-Release). Do not distribute an embargoed content item to news consumers until the release date-time found in embargoed has occurred.

  • withheld. Do not distribute this content item to news consumers because it contains questionable information. Any distributed form of the content item must be recalled.

  • canceled (the same as Kill). Do not distribute this content item to news consumers because it contains erroneous information. Any distributed form of the content item must be recalled.

    Important

    Do not use the pubstatus property alone to determine a content item's publishing status. Check the values of signals (newscontent), ednote, embargoed and editorialtypes to determine whether the content may be published. To learn more, see Identifying Publishable Content.

{// Example:
"pubstatus": "usable"}

editorialrole

The editorial role of a text or video content item.

For text, possible values are:

  • NewsAlert. A first, headline-length look at a breaking story.
  • FastStory. Used for either of the following:

    • AP NewsNow. A short story (130 words maximum) used for breaking news and non-urgent stories that can be told in 130 words.
    • The Latest. AP's special editorial representation of developing stories. To learn more, see The Latest - Developing Stories.
  • FullStory. A full-length AP news story.

  • Other. An AP news item that represents a collection of stories, such as a Headline Package.

For video, possible values are:

  • Package. A self-contained story with video and sound bites, including a prerecorded narration. AP provides packages with a script and the anchor narration on one channel and the natural sound and sound bites on a separate channel for the local station to rerecord the narration if necessary.
  • VO. Video to be voiced over live by an anchor in a newscast (an edited section of natural sound video showing the best pictures).
  • SOT. Sound on tape, with one or more sound bites edited together.
  • VOSOT. Video to be voiced over live by an anchor in a newscast followed by a sound bite or multiple sound bites.
{// Example:
"editorialrole": "VOSOT"}

fixture

Named sets of regularly occurring content or features with a predictable focus; for example, "Financial Impact," "Film Reviews," "10 Things to Know," "Sports Briefs." For more information, see a complete list of AP Fixtures.

Tip

This field is helpful for searching or grouping content in your own systems.

  • code. A code identifying the fixture.
  • name. The fixture name.
{// Example:
"fixture": {
  "code": "A60AC5A7AC024994B9102A73EFAB934A",
  "name": "Right Now"}

ednote

(API: May not be excluded) Editorial instructions for processing the item. Do not distribute this information to news consumers.

Important

In addition to the editorial notes in ednote, make sure to check for any special restrictions in usageterms and in the video script and/or shotlist (renditions.script_[format] and/or renditions.shotlist_[format]). For more information, see Usage Instructions and Pricing.

{// Example:
"ednote": "Eds: With AP Photos."}

editorialtypes

(API: May not be excluded) The editorial condition of the content item revision:

  • For text: Add, Advance, Advisory, Clarification, Corrective, Disregard, HoldForRelease, Kill, Lead, Writethru, Takes or Withhold.
  • For pictures: Correction, Elimination, Kill or Withhold.

Important

Make sure to check the editorialtypes values for any special processing instructions, especially Kills for pictures. To learn more, see Identifying Publishable Content.

{// Example:
"editorialtypes": ["Kill"]}

signals

(API: May not be excluded) Machine-readable instructions for processing the content item:

  • newscontent. Indicates that the content is publishable.

    Note

    If the newscontent signal is absent, the content is for editorial information only, not a news item and not intended for publication. Examples include advisories, daybooks and picture notification banners. To learn more, see Identifying Publishable Content.

  • APWhollyOwned. Indicates that all of the sources of the content item are AP wholly owned.

  • explicitcontent (Currently used only for video) Indicates that the news item contains graphic content.
  • test. Indicates test content.
  • derived and derivedlatest. (For text stories only) Indicates that the story type is 'The Latest,' and that it was derived from a more traditionally written version of the story. To learn more, see The Latest - Developing Stories.
  • isnotdigitized. (For video only) Indicates that a digital asset (for example, an archive video file) is not available for download.
  • NewsroomReady. (For video only) "Newsroom Ready" is generally loosely-edited and unvoiced video, without graphics. Video can be customized by editing elements and even branded as your own.
  • ConsumerReady. (For video only) "Consumer Ready" is fully-produced video with lower-third graphics, and often with reporter tracks.
  • whitelisted. (For archive video only) Indicates that all of the sources for an archive video content item appear on the whitelist.
  • singlesource. (For archive video only) Indicates that an archive video has only one source.
{// Example:
"signals": [
  "NewsroomReady",
  "APWhollyOwned",
  "newscontent"]}

title

A short publishable value containing the title of the current version of the content item.

{// Example:
"title": "France Royal Christmas Lights"}

headline

(API: Default) A brief synopsis of the current version of the content item. For pictures, this field may contain the names of the people featured in the picture.

{// Example:
"headline": "Toyota to start deploying vehicle-to-vehicle tech in 2021"}

headline_extended

Longer form headline for the text story.

{// Example:
"headline_extended": "Toyota says it will start equipping models with technology to talk to other vehicles starting in 2021, as it tries to push safety communications forward"}

description_summary

The story summary.

Note

Summary (description_summary) is an optional value to which your organization may or may not be entitled. For more information, contact us.

{// Example:
"description_summary": "U.S. industrial production jumped a solid 0.9 percent in October. Factory activity recovered from the previous months' shuttering of assembly lines by Hurricanes Harvey and Irma. The Federal Reserve says that manufacturing activity surged 1.3 percent last month. Many of the gains came from a sharp increase in the production of chemical and petroleum and coal products. Motor vehicles and metals also posted decent gains."}

bylines

(API: Default) The party who created or contributed to the content (if available and not captured in the photographer, producer or editor properties); for example, a writer (for text stories), an editor (for pictures) or a speaker (for audio). To learn more, see About Bylines.

  • by. The name(s) of the content creator(s) and/or contributors.
  • title. The title of the party referenced in the byline.
  • parametric. Additional information about the creator's or contributor's role.

    Note

    Photographers are identified in the photographer property. Video content does not typically contain a byline.

{// Example:
"bylines": [
 {"by": "By JOSH BOAK",
  "title": "AP Economics Writer"}]}

photographer

A party who created the content of this item; for example, a photographer for pictures.

  • code. A code identifying the photographer title.
  • name. The photographer's name.
  • title. The job title of the photographer.
{// Example:
"photographer": {
  "code": "CTR",
  "name": "John Milne/SilverHub/REX/Shutterstock",
  "title": "CONTRIBUTOR"}}

producer

A party that created or enhanced the content of this item.

  • name. The name of the content producer.
{// Example:
"producer": {
  "name": "mcrotty"}}

editor

A party that modified or enhanced the content.

  • name. The name of the content editor.
{// Example:
"editor": {
  "name": "rhacking@ap.org"}}

located

The location where the news event or subject described or depicted by the content occurred; for example, the dateline for text stories and location line for video.

{// Example:
"located": "Paris"}

datelinelocation

(API: Default) Contains detailed, uniform and machine-usable metadata about the location where the news event or subject described or depicted by the content occurred.

  • city. The location's city.
  • countrycode. An abbreviated form of the location's country.
  • countryname. The full name of the location's country.
  • countryareacode. The location's country area. A country area is a large-scale division within a country; for example, a U.S. state or Canadian province.
  • countryareaname. The full name of the location's country area. A country area is a large-scale division within a country; for example, a U.S. state or Canadian province.
  • geometry_geojson. A GeoJson object holding geo data of this place.
    • coordinates. Longitude and latitude of the location.
    • type. Geometry type: Point.
{// Example:
"datelinelocation": {
  "city": "Washington",
  "countryareacode": "DC",
  "countryareaname": "District of Columbia",
  "countrycode": "USA",
  "countryname": "United States",
  "geometry_geojson": {
    "type": "Point",
    "coordinates": [
      -77.03637,
      38.89511]}}

description_creditline

(API: May not be excluded) The party or parties that are credited with providing the content (a natural-language statement of credit information).

{// Example:
"description_creditline": "Diego Corredor/MediaPunch/MediaPunch/IPx"}

copyrightnotice

(API: May not be excluded) Any necessary copyright notice for claiming the intellectual property for the content.

{// Example:
"copyrightnotice": "Copyright 2018 The Associated Press. All rights reserved. This material may not be published, broadcast, rewritten or redistributed without permission."}

usageterms

(API: May not be excluded) Rights information and usage limitations associated with the publication, including any special restrictions. Do not distribute this information to news consumers.

Important

In addition to the special restrictions in usageterms, make sure to check for any additional use information and editorial notes in ednote and in the video script and/or shotlist (renditions.script_[format] and/or renditions.shotlist_[format]). For more information, see Usage Instructions and Pricing.

{// Example:
"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"]}

keywords

A displayable set of keywords relevant to a publication that can be used to expedite content searching in your own system.

{// Example:
"keywords": [
  "CROWN",
  "SERIES",
  "2",
  "WORLD",
  "PREMIERE",
  "ODEON",
  "LEICESTER",
  "SQUARE",
  "LONDON",
  "UK",
  "21",
  "NOV",
  "2017",
  "GILLIAN",
  "ANDERSON",
  "Actor",
  "Female",
  "Personality",
  "66289905"]}

outcue

The last spoken words heard on the audio, used to help editors and news anchors construct program scripts and resume speaking after the broadcast of an audio file.

{// Example:
"outcue": "in local media"}

provider

(API: May not be excluded) The name of the party (person or organization) that provided the content to the AP. This information may be different from the copyright and infosource.

{// Example:
"provider": "Europa Press"

infosource

A party (person or organization) that originated, modified, enhanced, distributed, aggregated or supplied the content or provided some information used to create or enhance the content. This information may be different from the copyright and provider.

  • name. The name of the infosource.
  • type. The source party's type in AP systems.
{// Example:
"infosource": [
  {"name": "Europa Press",
   "type": "ThirdParty"}]}

subject (including AP category code)

Concepts with a relationship to the content, such as topics, categories or subjects that describe the content, including:

  • AP Category Codes, which are applied to text, pictures, graphics and video by AP editors (identified by "rels":"category" in JSON).
  • AP Supplemental Categories, which are applied to pictures and graphics by AP editors (identified by "rels":"suppcategory" in JSON).
  • AP Subject terms, which are applied by the AP Classification system and cover a wide variety of topics from broad categories like 'Crime' to specific concepts like 'Illegal Firearms', breaking news events like 'Hurricane Maria' and recurring events like 'Academy Awards'. For a complete list of values, see AP Subject.

Tip

Use this field for searching or grouping content in your own systems, from routing content into your CMS buckets using AP category codes to automatically populating photo galleries by identifying images with topical subjects; for example, 'Celebrity' and 'Natural disasters'. Learn more >>

  • creator. Indicates the origin of the subject/category tag: Editorial (assigned by an AP editor) or Machine (assigned by the AP Classification system).

  • code. The code for the standardized subject term in the AP controlled vocabulary (http://cv.ap.org/id/), the AP category or the AP supplemental category.

  • scheme. The identifier of the AP controlled vocabulary.

  • name. The name of the AP subject, AP category or AP supplemental category.

  • parentids. The IDs of broader terms, if available.

  • rels. The relationship of the content of the news item to the subject.

    • direct. Indicates the AP Subject terms applied directly by the AP Classification system.
    • ancestor. Indicates the AP Subject terms inferred from hierarchy. For instance, 'Events' is a broader subject for 'September 11 attacks.'
    • inferred. Indicates the AP Subject terms inferred from relationships other than hierarchy, such as additional subject occurrences that are added based on entity or subject matches. For example, a match on 'September 11 attacks' ensures the application of the subject terms 'Terrorism' and 'War and unrest.'
    • category. Indicates AP category codes, which are applied to text, pictures, graphics and video by AP editors.
    • suppcategory. Indicates AP supplemental category codes, which are applied to pictures and graphics by AP editors.
  • topparent. The value of true indicates that this term is the top term in the AP Subject vocabulary hierarchy.

{// Example: AP Category Code
"subject": [
  {"rels": ["category"],
   "creator": "Editorial",
   "code": "e",
   "name": "Entertainment"}]}
{// Example: AP Category and Supplemental Category Codes
"subject": [
  {"rels": ["category"],
   "creator": "Editorial",
   "code": "A",
   "name": "Domestic News"},
  {"rels": ["suppcategory"],
   "creator": "Editorial",
   "code": "ENT",
   "name": "Entertainment"}}
{// Example: Subject tags applied by the AP Classification system
"subject": [
  {"creator": "Machine",
   "code": "b4ed19d87e5c10048565df092526b43e",
   "scheme": "http://cv.ap.org/id/",
   "name": "Celebrity",
   "parentids": ["5b4319707dd310048b23df092526b43e"],
   "rels": ["direct"]},
  {"creator": "Machine",
   "code": "5b4319707dd310048b23df092526b43e",
   "scheme": "http://cv.ap.org/id/",
   "name": "Entertainment",
   "parentids": ["16cb0ba3e6d24d97ace39f5a1924669a"],
   "rels": ["ancestor"]},
  {"creator": "Machine",
   "code": "16cb0ba3e6d24d97ace39f5a1924669a",
   "scheme": "http://cv.ap.org/id/",
   "topparent": true,
   "name": "Arts and entertainment",
   "rels": ["ancestor"]}]}

person

Individual human beings with a relationship to the content, such as named people mentioned in the content.

Tip

This field is helpful for searching or grouping content in your own systems. For example, you can build a web page for your hometown celebrity or athlete using their AP Person metadata to populate it dynamically with news about their lives and careers. Learn more >>

  • types. The main category that applies to a named individual; for example, POLITICIAN, ROYALTY, PROFESSIONAL_ATHLETE. For a complete list of values, see Person Type.

  • creator. Indicates the origin of the person tag: Editorial (assigned by an AP editor) or Machine (assigned by the AP Classification system).

  • code. The code for the person in the AP controlled vocabulary (http://cv.ap.org/id/).

  • scheme. The identifier of the AP controlled vocabulary.

  • name. The name of a person.

  • rels. The relationship(s) of the content of the news item to the person:

    • direct. Indicates that the term was applied directly by the AP Classification system (always true for persons).
    • PERSON_FEATURED. Indicates that this person is featured in the picture.
  • teams. (For team athletes and coaches only) The team values and codes are available as part of the list of AP Organization terms.

    • code. The team code in the AP Organization vocabulary.
    • name. The team name.
  • associatedevents. (Only for athletes and coaches participating in Olympic games or FIFA World Cup) Represents a relationship between a person and a current event, typically, the person's participation in or some significant contribution to the event; for example, a player's participation in 2018 FIFA World Cup. For more information, see Associated Event Name and Code Examples.

    • code. The code for the event in the AP controlled vocabulary.
    • name. The event name.
{// Example:
"person": [
  {"types": [
     "PROFESSIONAL_ATHLETE",
     "SPORTS_FIGURE",
     "PERSON"],
   "creator": "Machine",
   "code": "9921592d6bd64d8c95fadfd0425ee4da",
   "teams": [
     {"code": "718a0e588c0d10048d18e26cb3bf300e",
      "name": "FC Barcelona"}],
   "scheme": "http://cv.ap.org/id/",
   "name": "Lionel Messi",
   "rels": ["direct"]}]}

organisation

Organizations with a relationship to the content - administrative and functional structures that may act as a business, as a political party or not-for-profit party. Includes terms from AP Company (public companies with shares traded on major global and U.S. stock exchanges) and AP Organization (organizations such as government and non-profit organizations, sports teams, colleges, political groups, cultural and media organizations). For more information, see a complete list of AP Organization terms.

Tip

This field is helpful for searching or grouping content in your own systems. For example, you can precisely target content relevant to your favorite college teams, identify news about particular companies and industries, or track political news at state, national and international levels; for example, news about the government of California. Learn more >>

  • creator. Indicates the origin of the organization tag: Editorial (assigned by an AP editor) or Machine (assigned by the AP Classification system).

  • code. The code for the organization in the AP controlled vocabulary (http://cv.ap.org/id/).

  • scheme. The identifier of the AP controlled vocabulary.

  • name. The name of the organization/company.

  • parentids. The IDs of broader terms, if available.

  • rels. The relationship of the content of the news item to the organization.

    • direct. Indicates the terms applied directly by the AP Classification system. The relationship is always direct for public companies (AP Company terms).
    • ancestor. Indicates the terms inferred from hierarchy. For instance, 'Organizations' is a broader term for 'Museum of Modern Art.'
    • inferred. Indicates the terms inferred from relationships other than hierarchy, such as additional organization or subject occurrences that are added based on entity or subject matches. For example, a match on a sports team organization term 'Los Angeles Dodgers' ensures the application of the league organization term 'Major League Baseball' even if the 'Major League Baseball' tag application rule does not match the article. In another example, a national government 'Canada government' (organization term) ensures a match on its related concept 'Government and politics' (subject term) even if the 'Government and politics' rule does not match the article.
  • topparent. The value of true indicates that this term is the top term in the AP Organization vocabulary hierarchy.

  • industries. The industries related to the company.

    • name. The industry name.
    • code. The code for the industry in the AP Subject vocabulary.
  • symbols. Symbols used for a financial instrument linked to the company at a specific marketplace.

    • ticker. Ticker symbol used for the financial instrument.
    • exchange. Identifier for the marketplace which uses the ticker symbols of the ticker property. For a list of stock exchanges, see Stock Exchange Codes.
    • instrument. Combination of the company's ticker symbol and the stock exchange that it trades on, separated by a colon.
{// Example: Sports team
"organisation": [
  {"creator": "Machine",
   "code": "3dd152db3a744ba1b6d0c1c56b59ca62",
   "scheme": "http://cv.ap.org/id/",
   "name": "Seattle Seahawks",
   "parentids": ["07ae0c031fcb4519a43322bd50978599"],
   "rels": ["direct"]}}
{// Example: Public company
"organisation": [
  {"creator": "Machine",
   "code": "3d021e8e625c4c019e137512cc9154c4",
   "scheme": "http://cv.ap.org/id/",
   "industries": [
     {"code": "b5ed40a08bfa10048792a13d9888b73e",
      "name": "Discount store and superstore operators"},
     {"code": "8666f67f4af7f34e9c75ee532dcfd667",
      "name": "Multi-line retail"},
     {"code": "8fb64edaafc3bf4f9aa99a7ab679641b",
      "name": "Retail industry"},
     {"code": "d5547718dcb25e4ba562f2abf979255a",
      "name": "Retail and wholesale"},
     {"code": "5f8283e88bf910048037a13d9888b73e",
      "name": "Consumer services"},
     {"code": "31f4c0688adb10048f839a38be1dd83e",
      "name": "Consumer products and services"}],
   "name": "Target Corp",
   "symbols": [
     {"ticker": "TGTB34",
      "instrument": "BSP:TGTB34",
      "exchange": "BSP"},
     {"ticker": "TGT",
      "instrument": "NYS:TGT",
      "exchange": "NYS"}],
   "rels": ["direct"]}]}

place

Named locations mentioned in the content, such as continents, world regions, countries, territories, U.S. states, Canadian provinces and major cities. For more information, see a complete list of AP Geography terms.

Tip

This field is helpful for searching or grouping content in your own systems; for example, you can track breaking news events based on a combination of subject and geography metadata. Learn more >>

  • creator. Indicates the origin of the organization tag: Editorial (assigned by an AP editor) or Machine (assigned by the AP Classification system).

  • code. The code for the place the AP controlled vocabulary (http://cv.ap.org/id/).

  • scheme. The identifier of the AP controlled vocabulary.

  • name. The name of the place.

  • parentids. The IDs of broader terms, if available.

  • rels. The relationship of the content of the news item to the place.

    • direct. Indicates the terms applied directly by the AP Classification system.
    • ancestor. Indicates the terms inferred from hierarchy. For instance, 'North America' is a broader term for 'United States.'
  • topparent. The value of true indicates that this term is the top term in the AP Geography vocabulary hierarchy.

  • locationtype. The generic type of a geographic entity; for example, City, Province, Continent. For a list of values, see Location Type.

    • code. The code for the location type in the AP vocabulary.
    • name. The location type name.
  • geometry_geojson. A GeoJson object holding geo data of this place.

    • type. Geometry type: Point.
    • coordinates. Centroid coordinates - the WGS84 longitude and latitude of the location in decimal degrees.
{// Example:
"place": [
 {"code": "661e48387d5b10048291c076b8e3055c",
  "name": "United States",
  "rels": ["direct"],
  "scheme": "http://cv.ap.org/id/",
  "creator": "Machine",
  "parentids": ["661850e07d5b100481f7c076b8e3055c"],
  "locationtype": {
    "code": "01f56e0e654841eca2e69bf2cbcc0526",
    "name": "Nation" },
  "geometry_geojson": {
    "type": "Point",
    "coordinates": [
      -98.5,
      39.76 ]}},
 {"code": "661850e07d5b100481f7c076b8e3055c",
  "name": "North America",
  "rels": ["ancestor"],
  "scheme": "http://cv.ap.org/id/",
  "creator": "Machine",
  "topparent": true,
  "locationtype": {
    "code": "976d112cd5c3497ea180aeecab922c6b",
    "name": "Continent"},
  "geometry_geojson": {
    "type": "Point",
    "coordinates": [
      -100.54688,
      46.07323 ]}}]}

event

Something that happens in a planned or unplanned manner; for example, sports events or developing news events (such as The Latest).

  • name. The event name.
  • creator. Indicates the origin of the event tag.
  • externaleventids. External IDs of the event.

    • code. The external code for the event.
    • creator. The source of the external code.
    • creatorcode. Combination of the external event code and its source, separated by a colon.
  • eventproperties. Properties External event characteristics.

    • scheduleddatetime. The date and time when the event is scheduled to take place.
    • competitorname1 and competitorname2. Full names of the teams participating in the sports event.
    • competitorabbrv1 and competitorabbrv2. The abbreviations of the team names.
    • competitorqualifier1 and competitorqualifier2 Indicates whether the team is hosting the contest (Home) or visiting (Away).
    • seasonname. The name of the sports season during which the event is taking place.
    • tournamentname. The sports competition name.
    • venuename. The name of the venue where the sports event is taking place.
    • venuecapacity. The seating capacity: the number of people who can be seated in the venue.
{// Example: Sports event
"event": [
  {"name": "Buffalo Bills at Kansas City Chiefs 11/26/2017",
   "creator": "Machine",
   "externaleventids": [
     {"code": "57400",
      "creator": "sportradar",
      "creatorcode": "sportradar:57400"},
     {"code": "2017112603",
      "creator": "nfl",
      "creatorcode": "nfl:2017112603"}],
   "eventproperties": {
     "scheduleddatetime": "2017-11-26T18:00:00.000Z",
     "competitorname1": "Buffalo Bills",
     "competitorabbrv1": "BUF",
     "competitorqualifier1": "Away",
     "competitorname2": "Kansas City Chiefs",
     "competitorabbrv2": "KC",
     "competitorqualifier2": "Home",
     "seasonname": "NFL 2017 REG",
     "tournamentname": "Buffalo Bills at Kansas City Chiefs 11/26/2017",
     "venuename": "Arrowhead Stadium",
     "venuecapacity": "79451"}}]}
{// Example: Developing news event
"event": [
  {"creator": "Editorial",
   "code": "eb19f99cfbaa4fb280c4b3f7a37f8c51",
   "name": "Hawaii Volcano"}]}

audiences

An editorially selected designation of the audience (for example, geographic, demographic, economic group) that would have an interest in the content.

  • code. The code for the audience in the AP vocabulary.
  • name. The audience name.
  • type. The audience type.
{// Example:
"audiences": [
 {"code": "82c6a4c46fa0446090a7acaf93159e4c",
  "name": "Print",
  "type": "AUDPLATFORM"},
 {"code": "f5b16ea8760d10048047e6e7a0f4673e",
  "name": "State",
  "type": "AUDSCOPE"},
 {"code": "6e92d9b882c7100488e5df092526b43e",
  "name": "Texas",
  "type": "AUDGEOGRAPHY"}]}

description_caption

(API: Default) A freeform textual description of the content item.

{// Example:
"description_caption": "PITTSBURGH, PA - FEBRUARY 02: Pittsburgh Penguins Defenseman Kris Letang (58) turns with the puck during the third period in the NHL game between the Pittsburgh Penguins and the Washington Capitals on February 2, 2018, at PPG Paints Arena in Pittsburgh, PA. The Penguins defeated the Capitals 7-4. (Photo by Jeanine Leech/Icon Sportswire) (Icon Sportswire via AP Images)"}

description_editornotes

(API: May not be excluded) A section of text that is separate from the main story body, but is publishable.

{// Example:
"description_editornotes_text": "This is an AP member Exchange shared by the Waco Tribune-Herald"}

slugline

A non-publishable sequence of tokens associated with the content that is used as a short human-readable identifier for the content item and version.

{// Example:
"slugline": "BC-US--Julia Child Exhibit,1st Ld-Writethru"}

associations

(API: Default) Content of news items that are associated with this content item; for example, pictures and/or videos linked to a news story by AP editors or AP news stories that are part of AP Top Headlines. Each associated news item in the list of all news items associated with this content item is assigned a sequence number ("1", "2", "3" and so on). For example, if two pictures and two videos are associated with a news story (in that particular order), the "associationrank" will be "1" for the first picture, "2" for the second picture, "3" for the first video and "4" for the second video. The associated item properties include:

  • uri. The URL for the associated news item.
  • altids.itemid. The item ID of the associated news item.
  • altids.etag. A unique token for each revision of the associated news item, which helps detect duplicates. To learn more, see Managing Revisions and Duplicates.
  • type. The media type of the associated news item: text, picture, graphic, audio or video.
  • headline. A brief synopsis of the associated news item.
{// Example: Linked pictures and video
 "associations": {
   "1": {
     "uri": "https://api.ap.org/media/v/content/605bc7b95a8444ea8385a80710c296fa",
     "altids": {
       "itemid": "605bc7b95a8444ea8385a80710c296fa",
       "etag": "8c18ca6515194932995dd2513c14753e_0a1aza3c0"},
     "type": "picture",
     "headline": "Homeless Crisis on the Coast The Numbers"},
   "2": {
     "uri": "https://api.ap.org/media/v/content/6f72550bf5ad4c9185fdcbddf64f191f",
     "altids": {
       "itemid": "6f72550bf5ad4c9185fdcbddf64f191f",
       "etag": "5b215d671eae4639908a01f08bdf67fc_0a1aza3c0"},
     "type": "picture",
     "headline": "Homeless Crisis on the Coast The Numbers"},
   "3": {
     "uri": "https://api.ap.org/media/v/content/319355dd8d764629abb1310bb410da0b",
       "altids": {"itemid": "319355dd8d764629abb1310bb410da0b",
       "etag": "c64b4c02accd4b81ad6aa695d31e341c_0a1aza3c0"},
     "type": "video",
     "headline": "US Homeless Count Rises, Pushed by West Coast"}}}
{// Example: AP Top Headlines
 "associations": {
   "1": {
     "uri": "https://api.ap.org/media/v/content/b0d74bcf0ed146a2b681f6431d99789d",
     "altids": {
       "itemid": "b0d74bcf0ed146a2b681f6431d99789d",
       "etag": "8c18ca6515194932995dd2513c14753e_0a1aza3c0"},
     "type": "text",
     "headline": "UK hails new royal couple as country awaits wedding details"},
   "2": {
     "uri": "https://api.ap.org/media/v/content/aef7a9d725844217befd8070e3f384a2",
     "altids": {
       "itemid": "aef7a9d725844217befd8070e3f384a2",
       "etag": "5b215d671eae4639908a01f08bdf67fc_0a1aza3c0"},
     "type": "text",
     "headline": "UN: About 11 percent of drugs in poor countries are fake"},
   "3": {
     "uri": "https://api.ap.org/media/v/content/7d9b39c6a4444a3bb7bd8a433cca2cf5",
     "altids": {
       "itemid": "7d9b39c6a4444a3bb7bd8a433cca2cf5",
       "etag": "54c8d629d7e7405697af9a7ea13ad95c_0a1aza3c0"},
     "type": "text",
     "headline": "Russian weather satellite fails to enter orbit after launch"}}}

renditions

(API: Default) Wrapper for different renditions of the content item.

Note

All formats of the text renditions (stories, captions, scripts and shotlists) are returned by default. You can request specific formats using the text_links parameter.

Important

Always check the script and/or shotlist (renditions.script_[format] and/or renditions.shotlist_[format]) for any special restrictions on the use of the video content item.

Each rendition (for example, Main, Preview, Thumbnail, Caption, Script, Shotlist) contains the following optional properties:

  • title. The title of the content item rendition that can be used for posting on a website.

    {// Example:
    "title": "Full Resolution (MPG 720x576)"}
    
  • rel. The content item rendition; for example, Main, Preview, Thumbnail and Caption for images; and Main, Preview, Thumbnail, Caption, Script and/or Shotlist for video.

    {// Example:
    "rel": "Main"}
    
  • format. A format that applies to the rendition.

    {// Example:
    "format": "MPEG"}
    
  • type. The media type of the rendition: text, picture, graphic, audio or video.

    {// Example:
    "type": "video"}
    
  • contentid. A code used to identify the content item rendition.

    Tip

    The contentid values of the text renditions (for example, the NITF renditions of a video caption and a script) are not guaranteed to be unique. If you are using contentid values to name downloaded files, use rel and/or fileextension in addition to contentid to differentiate between the text renditions. For example, to save video captions and scripts with unique names, you can use the {itemid}-{version}-{contentid}-{rel}.{ext} file naming format.

    {// Example:
    "contentid": "305154376f4048089df0cdd5f8ccfeaa"}
    
  • digest. A short digest (also known as checksum or hash) of the rendition data (if available).

    {// Example:
    "digest": "7fe2d3d837069b2badf10bb3f8060710"}
    
  • href. The URL for accessing the rendition as a resource.

    Note

    The href property always contains a link to the latest version of the rendition. If versions=all is specified in the feed request, the links to all ANPA versions of the story are returned in renditions.anpa.version_links.

    {// Example:
    "href": "https://api.ap.org/media/v/content/1e3274d7fc7cf4b4a50793579ed18e12/download"}
    
  • version_links. (For ANPA stories only) The same story in the ANPA format may be filed multiple times; for example, with a different category code. When versions=all is specified in the request, the response includes links to all filings of ANPA-formatted stories in renditions.anpa.version_links. If versions=latest is specified in the request or if this parameter is not specified, only the latest filing of the ANPA story is returned in renditions.anpa.href.

    {// Example:
     "renditions": {    
       "anpa": {
         ...
         "href": "https://api.ap.org/media/v/content/d7473bea8b304ae2b78ee1d3a704885c.0/download?type=text&format=ANPA&{tokens4}",
         "version_links": [
           "https://api.ap.org/media/v/content/d7473bea8b304ae2b78ee1d3a704885c.0/download?type=text&format=ANPA&{tokens1}",
           "https://api.ap.org/media/v/content/d7473bea8b304ae2b78ee1d3a704885c.0/download?type=text&format=ANPA&{tokens2}",
           "https://api.ap.org/media/v/content/d7473bea8b304ae2b78ee1d3a704885c.0/download?type=text&format=ANPA&{tokens3}",
           "https://api.ap.org/media/v/content/d7473bea8b304ae2b78ee1d3a704885c.0/download?type=text&format=ANPA&{tokens4}"]}}
    
  • orientation. (For images only) The image orientation, which indicates whether the human interpretation of the top of the image is aligned to its short side (vertical) or long side (horizontal).

    • Horizontal (landscape images)
    • Vertical (portrait images)
    {// Example:
    "orientation": "Vertical"}
    
  • mimetype. A MIME type that applies to the rendition.

    {// Example:
    "mimetype": "video/mpeg"}
    
  • fileextension. The file extension of the content item.

    {// Example:
    "fileextension": "mpg"}
    
  • sizeinbytes. The size of the rendition resource in bytes.

    {// Example:
    "sizeinbytes": 125798400}
    
  • width. For still and moving images: the width of the display area measured in pixels.

    {// Example:
    "width": 720}
    
  • height. For still and moving images: the height of the display area measured in pixels.

    {// Example:
    "height": 576}
    
  • originalfilename. The name of the original media file.

    {// Example:
    "originalfilename": "4126150_PALESSENCE.mpg"}
    
  • duration. The total time duration of the content (in milliseconds for video; in seconds for audio).

    {// Example:
    "duration": 135800}
    
  • videocodec. The video encoding system used to create the content.

    {// Example:
    "videocodec": "MPEG"}
    
  • framerate. The number of video frames per second, which is the rate at which the material should be shown in order to achieve the intended visual effect.

    {// Example:
    "framerate": 25}
    
  • averagebitrate. The average amount of data that is transferred per second in the audio or video content.

    {// Example:
    "averagebitrate": "6144.000000"}
    
  • samplerate. The number of audio samples per second in the audio or video content, expressed as audio sampling frequency in hertz (Hz).

    {// Example:
    "samplerate": "25.000000"}
    
  • aspectratio. Aspect ratio of the video file, which is the ratio of the width of video to its height, such as 16:9 and 4:3.

    {// Example:
    "aspectratio": "16:9"}
    
  • videoscaling. Video scaling, which describes how the aspect ratio of a video has been changed from the original in order to accommodate a different display dimension:

    • pillarboxed. Bars to the left and right.
    • letterboxed. Bars to the top and bottom.
    • mixed. Two or more different aspect ratios are used in the video over the timeline.
    • original. No scaling has been applied.
    {// Example:
    "videoscaling": "original"}
    
  • resolution. The recording or image resolution of the content (if available):

    • For images: the recommended printing resolution in dots per inch.
    • For video: the number of distinct pixels in each dimension.
    • For audio: the recording resolution in bits per sample.
    {// Example:
    "resolution": 16}
    
  • colourspace. The color space of video or pictures (for example; Color or Black and White), if available.

    {// Example:
    "colourspace": "Color"}
    
  • scene. Description of recording scene; used only for images.

    {// Example:
    "scene": "Drawing"}
    
  • backgroundcolor. Image background color; typically used for graphics.

    {// Example:
    "backgroundcolour": "on gray"}
    
  • priced. The value of "true" indicates that downloading the rendition incurs a charge specified in the "pricetag" value (see below). If the "priced" property is not present, the rendition download does not result in a charge.

    Important

    When "priced": "true" is returned for the rendition, you must append &pricetag=<pricetag_value> to the rendition download link in addition to the apikey parameter. To learn more, see Acknowledging Pricing on Rendition Downloads.

  • pricetag. Indicates one of the following:

    • For downloads incurring a charge ("priced": "true"), describes the nature of the charge; for example, "USD:15.00" for a charge in actual currency or "MeterTick:1" for a charge in virtual currency.
    • For the main rendition downloads not resulting in a charge (the "priced" property is not present), indicates the type of the subscription; for example, "Unlimited" for a subscription with unlimited downloads.
    • For renditions that are not available for download (the "priced" property and the "href" download link are not present), indicates that the download is unavailable.

To learn more about renditions and view additional examples, see Item Renditions.

textformat

(For text stories only) Two-letter filing format code indicating the type of text set: - bt. Body type with one or more tabular lines. - at. Agate type with one or more tabular lines.
- ax. Agate type with no tabular lines. - bx. Body type or standard text.

{// Example:
"textformat": "bx"}

Contains external links; such as canonical links to full stories in AP News Archive. You can use canonical links to redirect web users to AP News Archive after your right to host AP content on websites expires at 30 days.

  • href. The URL for accessing the external content.
  • rel. The type of link to external content; for example, canonical.
{// Example:
"links": [
  {"href": "https://apnews.com/6d43bc91a1c44783878c7fdf85b58b49",
   "rel": "canonical"}]}