Item Metadata

 

ON THIS PAGE      Show

 

 

 

 

Description

Returns the content item data for the specified GUID, including metadata (either as JSON or XML in the NewsML-G2 format), links to all renditions of the content item (for example, the high-resolution, preview and thumbnail versions of a picture and the caption) and content item pricing information.

 

  Tips

 

  • It is recommended to use the item metadata links that are available in the search and feed responses. Learn more >>.

  • The item metadata links in the search or feed responses do not include the pricing=true, in_my_plan and format parameters.

    • To receive complete pricing information in the item metadata responses (including formatted price, use code and pricing message in addition to the price tags on renditions), add pricing=true to the item metadata links and supply the API key in the x-api-key request header.

    • To receive only those associations of the content item that do not incur any additional cost to download, add in_my_plan=true to the item metadata links and supply the API key in the x-api-key request header.

    • To receive item metadata as NewsML-G2 XML, add the format=newsmlg2 parameter to the item metadata links and supply the API key in the x-api-key  request header. For more information, see Response in NewsML-G2.

 

 

 

 

  Important

 

For video, always check the renditions.script_[format] and/or renditions.shotlist_[format] in the item metadata response for any special restrictions if you have not included these fields in the search or feed response.

 

 

 

Request

Required Request Header

  • x-api-key. Specifies the API key to authorize the request. The x-apikey header is also currently supported.

Optional Request Header

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

Request URI

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

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

Base URI Parameters

  • version (optional). The API version; for example, 2.0. When this parameter value is not specified, the API version set as default for your account is returned.
  • item_id (required). The 32-character GUID of a content item (not case-sensitive).

Optional Parameters

  • include, exclude. Parameters used to customize the fields returned in the response. For more information, see Customizing Response Fields.
  • pricing. Specifying pricing=true in the request returns complete pricing information for the content item, including formatted price, use code and pricing message in addition to the price tags on renditions, which are returned by default. For more information, see Pricing.

  • in_my_plan. Specifying in_my_plan=true in the request returns only those associations of the content item that do not incur any additional cost to download.

  • format. Specifying format=newsmlg2 in the request returns item metadata as XML in the NewsML-G2 format. For more information, see Response in NewsML-G2.

Request URI Examples

How to get item metadata in the NewsML-G2 format?

https://api.ap.org/media/v/content/ac6ce1e811664ef75b8a2ab2484a24d9?format=newsmlg2

How to get complete pricing information for a content item?

https://api.ap.org/media/v/content/fedf6ff0f6564fc29449f189d9242349?pricing=true

Response in JSON

Returns the standard HTTP status code of "200 - OK" and the content item data for the specified GUID in the JSON format.

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, account, download, ondemand, item, 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."
  • api_build. The API build number.
  • id. The response ID.
  • method. The API method name and HTTP method.
  • org_name. Organization name.
  • params. Parameters used in the API request.
  • data. Contains the data and metadata associated with the response.

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 (if applicable).
      • id. The Followed Topic ID.
      • name. The Followed Topic name.

Sample Response

{
  "api_version": "2.0",
  "api_mode": "live",
  "api_build": "2.0.2", 
  "id": "z5KyMgQ32",
  "method": "/content.GET",
  "org_name": "My Organization",
  "params": {},
  "data": {
    "meta": {
      "products": [
       // AP products to which the content item belongs
      ],
      "followedtopics": [
       // AP Newsroom Followed Topics to which the content item belongs
      ]
    },
    "item": {
     // Content metadata and download links
    }
  }
}

Response in NewsML-G2

When the format=newsmlg2 parameter is specified in the Item Metadata request, returns the standard HTTP status code of "200 - OK" and the content item data for the specified GUID as XML in the NewsML-G2 format. For more information, see Content Metadata Fields.

NewsML-G2 responses include price tags on priced downloads of content item renditions. These price tags must be used for acknowledging pricing on rendition downloads.

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, account, download, ondemand, item, 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.