Querying the API

cavis edited this page Oct 26, 2015 · 17 revisions

Overview

The PMP API supports a range of query parameters that can be used to filter results. The following page documents which query parameters are supported for use in queries and their usage.

Basic Usage

The query parameters can be used with any PMP API endpoint that is used to make a GET request for documents. The endpoints that can be queried are included in the query links of the Home document.

The most basic query looks like:

http://pmp.io/docs/

which would return all documents in the system that the user has permission to read. One subset of this could be retrieved as follows:

http://pmp.io/docs/?profile=audio;video

which would return all documents that have a profile of audio OR a profile of video and that the user has permission to read. And if there are still too many results, it could be further refined:

http://pmp.io/docs?profile=audio;video&startdate=2014-01-01&enddate=2014-01-31

which would return all documents that have a profile of audio OR video and that were published between January 1 2014 and January 31 2014 and that the user has permission to read.

The operators and fields used in these queries are further explained below.

Operators

Boolean Operators

  • ; - Boolean OR
  • , - Boolean AND
  • ! - Boolean NOT

Only one of OR/AND may be used with a search field. Use of both will result in unexpected results as the first operator encountered in the field will be used.

The NOT operator acts as a blacklist, always short-circuiting any docs that may have been included in the results.

Examples:

  • ?has=image,video,audio --> has items of profile (image AND video AND audio)
  • ?has=image;video;audio --> has an item of profile (image OR video OR audio)
  • ?has=image;video,audio --> BAD example, since both OR and AND are used, will be interpreted the same as above
  • ?has=image,video!audio --> has items of profile (image AND video) but DOES NOT HAVE an item of profile (audio)
  • ?has=image!video!audio --> has an item of profile (image) but DOES NOT HAVE items of profile (video OR audio)

Wildcards

Wildcards are not supported at this time.

Fields

The following fields are allowed in queries. Any combination of them is allowed except where specified below. Any of them support the Boolean operators except where specified below. Values are not case-sensitive.

In the omission of search params, all documents are included that the authenticated user has permission to read.

guid

  • Filters the results by the document guid according to the specified value(s). If omitted all documents are included. If a single guid is specified, only that document will be returned.
  • values
    • {guid} - the document guid
  • notes
    • Boolean AND not recommended as documents may only have one guid

limit

  • Limits the number of records per page in the response according to the specified value. If omitted the value defaults to 10.
  • notes
    • Does not allow the use of Boolean operators.

offset

  • Determines the record in the results with which to start the response according to the specified value. This effectively determines which page of results to display. If omitted the value defaults to 0.
  • notes
    • Does not allow the use of Boolean operators.

searchsort

  • Sorts the results according to the specified value. If omitted the value defaults to date.
  • values
    • date - default. sorts the results by published date, in descending order
    • dateasc - sorts the results by the published date, in ascending order
    • relevance - sorts the results by the strength of the match found while searching the index, in descending order
    • title - sorts according to the document attributes.title, ascending
    • titledesc - same as above, but in descending order
    • created - sorts the results by created date, in descending order
    • createdasc - sorts the results by the created date, in ascending order
    • distance - sorts by distance from a location, ascending (requires the location parameter be set)
  • notes
    • Does not allow the use of Boolean operators.

startdate

  • Filters the results by the documents' published attribute according to a range that uses the specified value as the starting date. If omitted all dates are included.
  • values
    • {date_string} - ISO-8601 formatted date to use as the starting date in the range.
  • notes
    • Does not allow the use of Boolean operators.

enddate

  • Filters the results by the documents' published attribute according to a range that uses the specified value as the ending date. If omitted all dates are included.
  • values
    • {date_string} - ISO-8601 formatted date to use as the ending date in the range
  • notes
    • Does not allow the use of Boolean operators.

startcreated

  • Filters the results by the documents' created attribute according to a range that uses the specified value as the starting date. If omitted all dates are included.
  • values
    • {date_string} - ISO-8601 formatted date to use as the starting date in the range.
  • notes
    • Does not allow the use of Boolean operators.

valid

  • Filters the results by the documents' valid.from and valid.to attributes.
  • values
    • false - default. Does not do any filtering by valid dates.
    • true - Only returns documents that are valid right now.
    • {date_string} - ISO-8601 formatted date to check for validity on.
  • notes
    • Does not allow the use of Boolean operators.

writeable

  • Filters the results by the documents' permission links according to the specified value. If omitted the value defaults to false and all documents are included.
  • values
    • false - default. Filters out all documents except those that the user has permission to read.
    • true - Filters out all documents except those that the user has permission to write.
  • notes
    • Does not allow the use of Boolean operators.

tag

  • Filters the results by the documents' tags attribute according to the specified value(s). If omitted all documents are included.

itag

  • Filters the results by the documents' itags attribute according to the specified value(s). If omitted all documents are included.
  • notes - this stands for "internal tags", and should be used for non-human-readable tag fields, such as an xid or xguid.

language

  • Filters the results by the documents' hreflang attribute according to the specified value(s). If omitted all documents are included.
  • notes
    • Boolean AND not recommended as documents may only have one language

profile

  • Filters the results by the documents' profile links according to the specified value(s). If omitted all documents are included.
  • values
    • {profile_id} - the guid or alias of the profile
  • notes
    • Boolean AND not recommended as documents may only have one profile.

collection

  • Filters the results by the documents' collection links according to the specified value(s). If omitted all documents are included.
  • values
    • {collection_guid} - the collection guid
  • notes
    • If the specified collection does not actually exist (the collection document was removed) then a 404 will be returned.
    • This search returns both items claiming a links.collection, and collections claiming a links.item.

item

  • Filters the results by the documents' item links according to the specified value(s). If omitted all documents are included.
  • values
    • {item_guid} - the item guid
  • notes
    • If the specified item does not actually exist then a 404 will be returned.
    • This search returns both collections claiming a links.item, and items claiming a links.collection.

has

  • Filters the results by the profile links of the documents' items according to the specified value(s). If omitted all documents are included.
  • values
    • {profile_id} - the guid or alias of the profile

creator

  • Filters the results by the documents' creator link according to the specified value. If omitted all documents are included.
  • value
    • {creator_guid} - the guid of the user or organization

owner

  • Filters the results by the documents' owner link according to the specified value. If omitted all documents are included.
  • value
    • {owner_guid} - the guid of the user or organization

distributor

  • Filters the results by the documents' distributor links according to the specified value(s). If omitted all documents are included.
  • values
    • {distributor_guid} - the distributor guid
  • notes
    • May not be used along with distributorgroup.

distributorgroup

  • Filters the results by the documents' distributor links according to the specified value. The specified value is treated as a group of distributors and expanded to a Boolean OR search term. The result is equivalent to using the distributor search field with Boolean OR operators. If omitted all documents are included.
  • values
    • {group_guid} - the guid of the group of distributors
  • notes
    • May not be used along with distributor.
    • Does not allow the use of Boolean operators.

author

  • Filters the results by the documents' author links according to the specified value(s). If omitted all documents are included.
  • values
    • {author_guid} - the author guid

location

  • Sets a location to search from. Must be used in conjunction with distance or searchsort=distance.
  • values
    • {latitude,longitude} - string lat/long numeric coordinates of the location, separated by a comma.

distance

  • Filter results to be within a certain distance of the location (required).
  • values
    • {distance[mi|km]} - string distance numeric, followed by either "mi" or "km" to specify the units desired.

text

  • Filters the results by full-text search on various text attributes in the documents according to the specified value(s). If omitted all documents are included.
  • notes
    • Does weighted full-text search against the title attribute, teaser attribute, byline attribute, and one of the content attributes: description, contenttemplated, contentencoded
    • The content attribute searched depends on which one was indexed as content, which is done according to the following order of precedence: description, contenttemplated, contentencoded
    • When used with searchsort=relevance the results will be ordered according to the weighted matches, where title has highest weight, then teaser, and then byline and content have the lowest weight.
    • This field also accepts quotes, booleans, wildcards, and generally anything available in the Elasticsearch query string syntax
    • Fields available for query string syntax include: title, teaser, byline, content, tags, itags
    • Also includes date fields: created, modified, valid.from, valid.to, published - but these will probably be less useful than the above text fields.
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.