Search

 

ON THIS PAGE      Show

 

 

 

 

 

If you are looking to ingest breaking news content into a Content Management System (CMS), use the Feed method instead. To learn about the differences between the Search and Feed methods, view typical workflows and try example requests, see Feed or Search? in Getting Started.

 

 

 

Description

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

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/search?[{optional_parameters}]

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.

For more information, see API Versions.

Optional Parameters

  • include, exclude. Parameters used to customize the fields returned in the response. For more information, see Customizing Response Fields.
  • 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.

  • in_my_plan. Specifying in_my_plan=true in the request returns only those items that do not incur any additional cost to download. Additionally, items returned include only those associations that do not incur any additional cost to download.
  • session_label. The tracking label to be applied to the session. The maximum number of characters in the label is 48, and only alphanumeric characters, periods, underscores and hyphens are allowed (a-z, A-Z, 0-9, . , _ and - ). For more information, see Labeling a Session Using a Request URL Parameter.

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, 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.
  • session_label. A session tracking label applied either by adding the session_label={yourLabel} parameter to your request URL or by entering the Content Management System (CMS) name and version for your agent in the CMS Name and Version box on the Manage Ingest page of the Agent Dashboard. For more information, see Session Labels.
  • 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. Note that optional parameters supported by Search and Feed requests are not identical; for example, the sort search parameter is not supported for feeds. Therefore, only Search parameters common with Feed are transitioned over.
  • 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.

 

 

 

 

Sample Search Response

This example shows a response to the following request (the API key is supplied in the x-api-key request header):

https://api.ap.org/media/v/content/search?q=Emma+Stone&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": "2.0",
  "api_mode": "live",
  "api_build": "2.0.2", 
  "id": "Hy3I1nqjZ",
  "method": "/content/search.GET",
  "org_name": "My Organization",
  "params": {
    "include": [
      "*"
    ],
    "pricing": true,
    "q": "Emma Stone"
  },
  "data": {
    "query": "Emma Stone",
    "updated": "2020-07-02T17: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 instructions and pricing
              }
           }
        },
        "item": {
          // Human-readable usage terms, content metadata and download links
        }
      }
    ]
  }
}