Search and Feed - esinyavsky/Content-API-V3-Documentation GitHub Wiki

Search Method

Description

Searches content using the specified search criteria. Optionally, returns content item pricing information.

Request

  • Method: GET
  • Request URI:
https://api.ap.org/[{version}]/content/search?api_key={api_key}[{optional_parameters}]

Important: The request URI must be URL-encoded.

Base URI Parameter

  • version (optional): The API version; for example, v2. When this parameter value is not specified, the latest API version is returned.

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: A comma-separated list of fields to include in the response.

  • exclude: A comma-separated list of fields to exclude from the response.

  • view: Returns a predefined set of fields for each content item:

    • basic: A limited set of fields (this is the default).
    • full: All available fields.

  • content_set: The content set to be searched. For the AP Images content, valid options are:

    • editorial: Editorial images.
    • creativeRM: Creative rights-managed images.
    • creativeRF: Creative royalty-free images.
    • GraphicsBank: All GraphicsBank content.
    • GraphicsBank_Graphic: Graphics content from GraphicsBank.
    • GraphicsBank_Photo: Photo content from GraphicsBank.
    • all: All available content sets (this is the default).

  • pricing. By default, pricing information is not returned in the response. When pricing=true is specified in the request, the response includes pricing for each content item.

  • all_filings. When all_filings=true is specified in the request, the response includes all filings of ANPA and/or IPTC-formatted stories. If this parameter is not used, only the latest filing of a story is returned.

  • page: The requested page number within the set of search results. The default is 1.

  • page_size: The maximum number of results to return per page. The default is 25 results with a maximum of 100 per page.

  • sort: The sort order of the returned results.

  • parametrics: By default, query facets that allow you to refine the original search are returned for each content item at the entry level only. When parametrics=true is specified in the request, the response also includes query facets for the entire result set in the "queries" array at the top of the JSON response.

  • format: The response format (currently, the only valid value is json). If no format is specified as the format parameter value or in the Accept header, JSON is returned. The format parameter value takes precedence over the Accept header value when both are specified.

Request Headers (Optional)

  • Accept: The MIME type of the returned data format (currently, only JSON is supported). The default is application/json. The format parameter value takes precedence over the Accept header value when both are specified.

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

Request URI Examples

Example 1. This request returns content items that match both keywords ("Tom" and "Brady"), including pricing information for each item:

https://api.ap.org/content/search?api_key={api_key}&q=Tom+Brady&pricing=true

Example 2. This request returns content items that match the keyword "soccer" that arrived later than ten days ago:

https://api.ap.org/content/search?api_key={api_key}&q=soccer+AND+arrivaldate>10daysAgo

Example 3. This request returns all GraphicsBank graphics that match the keyword "football" and illustrate a news event that took place on November 9, 2016:

https://api.ap.org/content/search?api_key={api_key}&q=football+AND+creationDate=2016-11-09&content_set=GraphicsBank_Graphic

Feed Method

Description

Returns a feed of content matching the specified criteria. Optionally, returns content item pricing information.

Request

  • Method: GET
  • Request URI:
https://api.ap.org/[{version}]/content/feed?api_key={api_key}[{optional_parameters}]

Important: The request URI must be URL-encoded.

Base Request URI Parameter

  • version (optional): The API version; for example, v2. When this parameter value is not specified, the latest API version 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: A comma-separated list of fields to include in the response.

  • exclude: A comma-separated list of fields to exclude from the response.

  • view: Returns a predefined set of fields for each content item:

    • basic: A limited set of fields (this is the default).
    • full: All available fields.

  • content_set: The content set to be searched. For the AP Images content, valid options are:

    • editorial: Editorial images.
    • creativeRM: Creative rights-managed images.
    • creativeRF: Creative royalty-free images.
    • GraphicsBank: All GraphicsBank content.
    • GraphicsBank_Graphic: Graphics content from GraphicsBank.
    • GraphicsBank_Photo: Photo content from GraphicsBank.
    • all: All available content sets (this is the default).

  • pricing. By default, pricing information is not returned in the response. When pricing=true is specified in the request, the response includes pricing for each content item.

  • all_filings. When all_filings=true is specified in the request, the response includes all filings of ANPA and/or IPTC-formatted stories. If this parameter is not used, only the latest filing of a story is returned.

  • page: The requested page number within the set of search results. The default is 1.

  • page_size: The maximum number of results to return per page. The default is 25 results with a maximum of 100 per page.

  • format: The response format (currently, the only valid value is json). If no format is specified as the format parameter value or in the Accept header, JSON is returned. The format parameter value takes precedence over the Accept header value when both are specified.

Request Headers (Optional)

  • Accept: The MIME type of the returned data format (currently, only JSON is supported). The default is application/json. The format parameter value takes precedence over the Accept header value when both are specified.

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

Supported Query Syntax