Account Plans

 

ON THIS PAGE      Show

 

 

 

 

Description

Returns your plan details in JSON or CSV format and allows you to check how many downloads or if applicable, credits you have already used (reflects transactions as of the date and time of the 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}]/account/plans

Base URI Parameter

  • 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.

Optional Parameters

  • include, exclude. Parameters used to customize the fields returned in the response. For more information, see Customizing Response Fields.
  • format. The response format (json or csv). By default, JSON is returned.

Request URI Example

https://api.ap.org/media/v/account/plans

Response

The Account Plans method returns the standard HTTP status code of "200 - OK" and your plan details and usage information for the specified API key in the requested format (JSON or CSV).

If CSV is requested, the default file name format is OrgName_date.csv; for example, Boston_Herald_2023-08-06.csv.

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.

Response Descriptive Properties

  • id. The Account Plans URL.
  • title. The response name.
  • updated. The date and time (in UTC) when the response was generated.
  • plans. Contains the data and metadata associated with an individual account plan information and usage.

Plan Descriptive Properties

  • id. The plan ID.
  • name. The plan name.
  • updated. The date and time (in UTC) when the plan information was last updated.
  • plan_style. Indicates how the used downloads are reported (if applicable):
    • percent (for plans such as Choice)
    • downloads (the actual number of downloads since the beginning of the current billing cycle)
    • duration (indicates unlimited downloads of certain sets of content within a certain period; for example, where the content up to 14 days old is included in the plan, and an extra charge applies to older content)
    • credits (account is limited to a certain number of credits per month; each download costs a certain number of credits indicated in the entitlement description and the item metadata; an extra charge applies to additional downloads once the plan's credit limit is reached)
  • used. Depending on the plan style, indicates the percent/number of downloads or credits already used, if available.
  • usage_limit. For download-style plans, indicates the total number of downloads allowed during a billing cycle (not including downloads for an extra charge). If your plan allows for unlimited downloads, usage_limit is not returned. For percent-style plans, this value is always 100 (100%). For credit-style plans, indicates the total number of credits available during a billing cycle.
  • duration. For duration-based plans, the length of time during which content is included in the plan. For possible values, refer to ISO 8601 Durations.
  • interval. The length of the billing cycle. For possible values, refer to ISO 8601 Durations.
  • next_cycle_begins. Indicates the start date of the next billing cycle.
  • entitlements. Contains the data and metadata associated with an individual entitlement.

Entitlement Descriptive Properties

  • id. The entitlement ID (AP product ID or AP package ID).
  • name. The entitlement name.
  • tier. (For plans such as Choice) The name of your plan tier to which this content offering belongs.
  • type. The entitlement type:
    • Product: A standard AP news service or report, which is defined by a name, a product ID number and a description; for example, AP Online National News.
    • Package: A collection of AP products.
  • sub_type. The entitlement subtype:
    • Breaking News: Content in this AP product/package is not available for Search if it is more than 30 days old.
    • Archive: Content in this AP product/package is not available for Search if it is less than two days old and is not available for Feed at all.
    • Full: Includes both Breaking News and Archive content. Most AP products and packages fall into this subtype.
  • media_type. (For products) The media type of the content included in the product; for example, Text, Picture, Graphic, Video.
  • parent_id. (For products) The ID of the package that includes this product (shown only if your organization is not entitled to this product directly).
  • base_cost. Price per content item when the content item is included in the plan (if applicable).
  • overage_allowed. Indicates whether your plan allows you to download content items for an extra charge if the plan limit is reached or the item is outside of the plan's duration. Possible values are true and false.
  • overage_cost. Price per content item (extra charge) if the content item is out of the plan or if the plan limit is reached.
  • currency. The currency in which the prices are returned.
  • meter_ticks. The charge per content item in meter ticks, which indicates how many download units are deducted from your meter once the content item is downloaded. A meter tick is a form of virtual currency for content items included in your download-style plan with a download limit (metered plan).
  • credits. The charge per content item in credits, which indicates how many credits are deducted from your meter once the content item is downloaded. A credit is a form of virtual currency for content items included in your credit-style plan with a credit limit (metered credits plan).
  • search_link. A link to the results of a search by this entitlement ID.
  • feed_link. A link to the feed of content matching this entitlement ID.

Examples

Metered Plan Example

This example shows a metered plan that allows 100 downloads per month for three sample products. Each download of the "GraphicsBank - All" product content counts for one meter tick, and each download of content included in the other two products counts for two meter ticks.

{
 "api_version": "2.0",
 "api_mode": "live",
 "api_build": "2.0.2",
 "id": "S1Z8VDP0Z",
 "method": "/account/plans.GET",
 "org_name": "My Organization",
 "params": {},
 "data": {
   "id": "https://api.ap.org/media/v/account/plans",
   "title": "My Plans",
   "updated": "2023-07-02T16:19:29.616Z",
   "plans": [
    {
     "id": 123,
     "name": "Metered Plan",
     "updated": "2023-07-02T16:19:29.616Z",
     "plan_style": "downloads",
     "used": 0,
     "usage_limit": 100,
     "interval": "P1M",
     "next_cycle_begins": "2020-08-01",
     "entitlements": [
      {
       "id": 42460,
       "name": "AP Exclusive Photo (World)",
       "type": "Product",
       "sub_type": "Full",
       "media_type": "Picture",
       "meter_ticks": 2,
       "overage_allowed": false,
       "search_link": "https://api.ap.org/media/v/content/search?q=productid:42460",
       "feed_link": "https://api.ap.org/media/v/content/feed?q=productid:42460"
      },
      {
       "id": 42906,
       "name": "AP Premium Photo",
       "type": "Product",
       "sub_type": "Full",
       "media_type": "Picture",
       "meter_ticks": 2,
       "overage_allowed": false,
       "search_link": "https://api.ap.org/media/v/content/search?q=productid:42906",
       "feed_link": "https://api.ap.org/media/v/feed?q=productid:42906"
      },
      {
       "id": 38474,
       "name": "Graphics Bank - All",
       "type": "Product",
       "sub_type": "Full",
       "media_type": "Picture", 
       "meter_ticks": 1,
       "overage_allowed": false,
       "search_link": "https://api.ap.org/media/v/content/search?q=productid:38474",
       "feed_link": "https://api.ap.org/media/v/content/feed?q=productid:38474"
      }]
    }]
  }
}

Metered Credits Plan Example

This example shows a metered credits plan that is limited to 500 credits per month for one sample product. Each download of the "Invision / Photostream" product content counts for three credits, and an extra charge applies to each additional download when the plan limit is reached.

{
 "id": 121813,
 "name": "Metered Credits Plan",
 "updated": "2022-11-02T19:39:33.537Z",
 "plan_style": "credits",
 "used": 0,
 "usage_limit": 500,
 "interval": "P1M",
 "next_cycle_begins": "2022-12-01",
 "entitlements": [
  {
   "id": 44216,
   "name": "Invision / Photostream",
   "type": "Product",
   "sub_type": "Full",
   "media_type": "Picture",
   "credits": 3,
   "overage_allowed": true,
   "overage_cost": 98.49,
   "currency":"USD",
   "search_link": "https://api.ap.org/media/v/content/search?q=productid:44216",
   "feed_link": "https://api.ap.org/media/v/feed?q=productid:44216"
  }
 ]
}

Unlimited Subscription Example

This example shows a plan that allows unlimited downloads of content for two sample entitlements (no "usage_limit" is returned for this plan).

{
 "id": 72791,
 "name": "Unlimited Subscription",
 "updated": "2023-07-02T17:28:14.051Z",
 "plan_style": "downloads",
 "interval": "P1M",
 "next_cycle_begins": "2023-08-01",
 "entitlements": [
   {
    "id": 31989,
    "name": "AP Online Top General Headlines",
    "type": "Product",
    "sub_type": "Full",
    "media_type": "Text",
    "overage_allowed": false,
    "search_link": "https://api.ap.org/media/v/content/search?q=productid:31989",
    "feed_link": "https://api.ap.org/media/v/content/feed?q=productid:31989"
   },
   {
    "id": 100100,
    "name": "GraphicsBank",
    "type": "Package",
    "sub_type": "Full",
    "overage_allowed": false,
    "search_link": "https://api.ap.org/media/v/content/search?q=productid:100100",
    "feed_link": "https://api.ap.org/media/v/content/feed?q=productid:100100"
   }
  ]
 }

Limited Duration Subscription Example

This example shows a plan with duration-based pricing where the content up to 14 days old is included in the plan, and an extra charge applies to older content. In this example, only one entitlement is shown for brevity.

{
 "id": 22519,
 "name": "Limited Duration Subscription",
 "updated": "2023-07-02T14:59:52.675Z",
 "plan_style": "duration",
 "duration": "P14D",
 "interval": "P1M",
 "next_cycle_begins": "2023-08-01",
 "entitlements": [
   {
    "id": 42461,
    "name": "AP Exclusive Photo (World) - Browse only",
    "type": "Product",
    "sub_type": "Full",
    "media_type": "Picture",
    "overage_allowed": true,
    "overage_cost": 35,
    "currency": "USD",
    "search_link": "https://api.ap.org/media/v/content/search?q=productid:42461",
    "feed_link": "https://api.ap.org/media/v/content/feed?q=productid:42461"
   }
  ]
 }

Choice Plan Example

This example shows a PhotoChoice plan, which has multiple tiers of content, with each content offering having a different price based on the tier to which they belong. In this example, only one or two entitlements per tier are shown for brevity.

{
 "id": 90225,
 "name": "Choice Plan",
 "updated": "2023-07-02T20:23:58.729Z",
 "plan_style": "percent",
 "used": 0,
 "usage_limit": 100,
 "interval": "P1M",
 "next_cycle_begins": "2023-08-01",
 "entitlements": [
   {
    "id": 1206,
    "name": "APstrmPhotos",
    "tier": "Tier 1 - PhotoChoice",
    "type": "Package",
    "sub_type": "Full",
    "base_cost": 1.5,
    "overage_allowed": true,
    "overage_cost": 42,
    "currency": "USD",
    "search_link": "https://api.ap.org/media/v/content/search?q=productid:1206",
    "feed_link": "https://api.ap.org/media/v/content/feed?q=productid:1206" 
   },
   {
    "id": 40510,
    "name": "NFL Outtakes",
    "tier": "Tier 1 - PhotoChoice",
    "type": "Product",
    "sub_type": "Full",
    "media_type": "Picture",
    "base_cost": 1.5,
    "overage_allowed": true,
    "overage_cost": 42,
    "currency": "USD",
    "search_link": "https://api.ap.org/media/v/content/search?q=productid:40510",
    "feed_link": "https://api.ap.org/media/v/content/feed?q=productid:40510"
   },
   {
    "id": 42666,
    "name": "Sports Contributor",
    "tier": "Tier 2 - PhotoChoice",
    "type": "Product",
    "sub_type": "Full"
    "media_type": "Picture",
    "base_cost": 5,
    "overage_allowed": true,
    "overage_cost": 125,
    "currency": "USD",
    "search_link": "https://api.ap.org/media/v/content/search?q=productid:42666",
    "feed_link": "https://api.ap.org/media/v/content/feed?q=productid:42666"
   },
   {
    "id": 10017,
    "name": "Canadian Press (Photostream)",
    "tier": "Tier 3 - PhotoChoice",
    "type": "Product",
    "sub_type": "Full",
    "media_type": "Picture", 
    "base_cost": 10,
    "overage_allowed": true,
    "overage_cost": 225,
    "currency": "USD",
    "search_link": "https://api.ap.org/media/v/content/search?q=productid:10017",
    "feed_link": "https://api.ap.org/media/v/content/feed?q=productid:10017"
   },
   {
    "id": 43699,
    "name": "Top Photo",
    "tier": "Tier 4 - PhotoChoice",
    "type": "Product",
    "sub_type": "Full",
    "media_type": "Picture",
    "base_cost": 25,
    "overage_allowed": true,
    "overage_cost": 450,
    "currency": "USD",
    "search_link": "https://api.ap.org/media/v/content/search?q=productid:43699",
    "feed_link": "https://api.ap.org/media/v/content/feed?q=productid:43699"
   },
   {
    "id": 40645,
    "name": "NFL Contributor",
    "tier": "Tier 5 - PhotoChoice",
    "type": "Product",
    "sub_type": "Full",
    "media_type": "Picture",
    "base_cost": 50,
    "overage_allowed": true,
    "overage_cost": 950,
    "currency": "USD",
    "search_link": "https://api.ap.org/media/v/content/search?q=productid:40645",
    "feed_link": "https://api.ap.org/media/v/content/feed?q=productid:40645"
   }
  ]
 }

A La Carte Plan Example

This example shows a plan that allows a la cart downloads of content for two sample entitlements, with the indicated base price charged for each download.

{
 "id": 25681,
 "name": "A La Carte Plan",
 "updated": "2023-07-02T15:12:08.541Z",
 "plan_style": "downloads",
 "used": 0,
 "interval": "P1M",
 "next_cycle_begins": "2023-08-01",
 "entitlements": [
   {
    "id": 41758,
    "name": "Canadian Press Archive",
    "type": "Product",
    "sub_type": "Full",
    "media_type": "Picture",
    "base_cost": 35,
    "overage_allowed": false,
    "currency": "USD",
    "search_link": "https://api.ap.org/media/v/content/search?q=productid:41758",
    "feed_link": "https://api.ap.org/media/v/content/feed?q=productid:41758"
   },
   {
    "id": 42068,
    "name": "Canadian Press Extra",
    "type": "Product",
    "sub_type": "Full",
    "media_type": "Picture",
    "base_cost": 35,
    "overage_allowed": false,
    "currency": "USD",
    "search_link": "https://api.ap.org/media/v/content/search?q=productid:42068",
    "feed_link": "https://api.ap.org/media/v/content/feed?q=productid:42068"
   }
  ]
 }