Browse information objects endpoint¶

Boolean criteria parameters¶

• sq0: Query string. Used submit search terms.
• so0: Query operator. Available options are and, or, and not. The default operator when the parameter is not included is and.
• sf0: Query field. Used to limit the boolean parameters to searching within a specific field of the information objects. Options include:
  • _all : Search all indexed fields. When no sf0 parameter is included, this is the default.
  • title: Limit boolean search query to title field - the formal or supplied title of the description; equivalent to ISAD(G) 3.1.2.
  • identifier: Limit boolean search to the identifier field.
  • referenceCode: Limit boolean search to the full inherited reference code value of descriptions
  • scopeAndContent: Limit boolean search query to the Scope and content field; equivalent to ISAD(G) 3.3.1
  • archivalHistory: Limit boolean search query to the Archival history field; equivalent to ISAD(G) 3.2.3
  • extentAndMedium: Limit boolean search query to the Extent and medium field; equivalent to ISAD(G) 3.1.5
  • genre: Limit boolean search query to genre access points associated with descriptions.
  • subject: Limit boolean search query to subject access points associated with descriptions.
  • name: Limit boolean search query to name access points associated with descriptions (e.g. authority records associated with a description not as a creator but as a name access point).
  • place: Limit boolean search query to place access points associated with descriptions.

An unlimited number of criteria can be sent by incrementally increasing the number in the above parameters (e.g. sq1, so1, sf1, etc). They must by consecutive numbers starting at zero and the only required parameter is the query string.

Tip

It is possible to pass query operators within a single combined string by directly adding AND, OR, or AND NOT to your query string value. This is best tested and explored by playing with the advanced search interface in AtoM, and using the URL parameters returned with the response as parameters for the API. For example, if you use the advanced search interface, and add “taxes AND investments” to the query field, and limit it to Scope and content, the parameters passed via the URL when the results are returned are:

/api/informationobjects/?sq0=taxes+AND+investments&sf0=scopeAndContent

This is the same as manually increasing the parameter numbers and repeating the criteria indivudually, like so:

/api/informationobjects?sq0=taxes&sfo=scopeAndContent&sq1=investments&sf1=scopeAndContent

See the examples below for more instances of this.

You can also use other boolean operators to enhance the results returned such as * wildcards or ~ fuzzy searching. For more information on available boolean operators, see: Boolean operators in the Advanced search documentation.

Note that the boolean criteria parameters can also be used in combination with the filter parameters outlined below.

Example requests with Boolean criteria¶

Return results with conveyance AND issuing in scope and content:

/api/informationobjects?sq0=conveyance+AND+issuing&sf0=scopeAndContent

Or, this could also be expressed as:

/api/informationobjects?sq0=conveyance&sf0=scopeAndContent&sq1=issuing&sf1=scopeAndContent

Return results with "conveyance issuing" (e.g. that exact string) in Scope and content:

/api/informationobjects?sq0="conveyance+issuing"&sf0=scopeAndContent

Return results with conveyance OR issuing in the scope and content field:

/api/informationobjects?sq0=conveyance+issuing&sf0=scopeAndContent

Return results with coffee OR chocolate in any field, AND (photo* OR picture* OR image*) in Extent and medium:

/api/informationobjects?sq0=chocolate&so1=or&sq1=coffee&so2=and&sq2=photo*+OR+picture*+OR+image*&sf2=extentAndMedium&topLod=0

Filter parameters¶

The filter parameters below are the same as those found in the user interface as part of the Advanced search module, with some small variations (such as the skip parameter).

In many cases, the parameters expect internal IDs as the values for the parameters. Since these ids are automatically generated via mysql autonumerics (and thus subject to change over time), and because all terms in AtoM exist in user-editable taxonomies, it is not possible to list all available options for each parameter - it will depend on the data in your particular system. For some values, you can find a list of some of the default term IDs in lib/model/QubitTerm.php, or you can always perform an advanced search via the user interface, and then look at the resulting URL to see how the parameter has been passed - the same parameter and ID can be used in the API.

SELECT term.id, term_i18n.name FROM term LEFT JOIN term_i18n ON (term.id = term_i18n.id) WHERE term.taxonomy_id = (SELECT id FROM taxonomy_i18n WHERE culture = 'en' AND name = 'Genre') AND term_i18n.culture = 'en';

Filter parameters available for the Browse information object endpoint include:

• sf_culture: ISO 639-1 language code for display. See Common parameter - i18n culture for more information on this parameter.
• limit: The maximum number of information objects returned in a single response. Note that this parameter is limited by the Results per page global setting - you can use this parameter to limit the response further (e.g. request less results than the global setting), but increasing the limit parameter will not override the Results per page setting value.
  • Example - return only 5 results per request: /api/informationobjects?limit=5
• skip: The amount of information objects skipped when returning the results. This parameter can be used to page results - for example, if the first response includes 10 results, then the following request can include a skip=10 parameter, which will skip the first 10 results and begin the response on the 11th. See the examples below.
  • Example - Skip the first 20 results: /api/informationobjects?skip=20
• sort: This parameter offers the user options to sort the results. The options available are identical to those found in the Sort buttons for archival descriptions, and are described below. When the parameter is not included, the default sort order is whatever has been set in the Sort browser (users) setting. Otions:
  • identifier: sort results by reference code
  • alphabetic: sort results alphabetically. Note that in AtoM, alphabetic sorting uses ASCII sorting, not natural sorting - see this article for a bit more on the difference.
  • date: sorted by the internal startDate value, which should be ISO-8601 formatted (e.g. YYYY-MM-DD, YYYY-MM, or YYYY)
  • lastUpdated: sorted by most recent created or modified date
  • Example - sort by most recently created/modified: /api/informationobjects?sort=lastUpdated
• topLod: Return only top level descriptions, or all descriptions. Equivalent to the top-level descriptions filter (which is on by default in the archival description browse page, but off by default on search results pages) in the user interface. When the parameter is not included, the default is to return all levels of description (e.g. topLod=0) Options:
  • 0: all results
  • 1: only top-level descriptions
  • Example - return only top-level descriptions: /api/informationobjects?topLod=1
• onlyMedia: Return results with a linked digital object, or all descriptions. The default when this parameter is not included is to return all descriptions (e.g. onlyMedia=0). Options:
  • 0: Return all descriptions
  • 1: Return only descriptions with a linked digital object
  • Example - return descriptions with a digital object: /api/informationobjects?onlyMedia=1
• copyrightStatus: Return records with a particular copyright status, based on PREMIS rights statements associated with the description. For more information on PREMIS rights in AtoM, see: Rights. Expects the internal ID of a particular term from the Copyright status taxonomy as the value.
  • Example - Return records with a PREMIS rights statement that indicates they are under copyright: /api/informationobjects?copyrightStatus=335
• materialType: Relates to the Canadian RAD standard’s General material desgination (GMD) terms - terms are found in AtoM’s Material type taxonomy. Returns results limited to those linked to a particular GMD term. Expects the internal ID of a particular term from the Material type taxonomy as its value.
  • Example - Return records with a General material designation of “Moving images”: /api/informationobjects?materialType=264
• languages: Equivalent to the languages facet in the user interface, which limits the results of a request to descriptions in a specific language. Expects an ISO 639-1 language code.
  • Example - return records in French: /api/informationobjects?languages=fr
• levels: Return results limited to a specified level of description. Expects a term ID from the Levels of description taxonomy as the parameter value. Like all taxonomy terms in AtoM, these terms can be user-defined, so the IDs may vary.
  • Example - Return records with a level of description of “Series”: /api/informationobjects?levels=224
• mediatypes: Filters results based on the digital object linked to the descriptions returned. Expects the internal id of the default terms used in the Media type taxonomy:
  • Example - Return records with a linked digital object that is an image: /api/informationobjects?mediatypes=136
• repos: Returns records filtered by their association to a particular repository (e.g. an archival institution). Only really useful as a parameter in a multi-repository AtoM installation. Expects the internal repository ID as a value - AtoM does not include default archival institutions during installation, so these IDs will depend on user data.
  • Example - Return records associated with the Example Archives (example ID = 827): /api/informationobjects?repos=827
• places: Returns records filtered by their association to a particular place access point. For more information on linking an archival description to an access point, see: Add an access point “on the fly” from an archival description. Expects the internal place term ID as a value - AtoM does not include default place terms during installation, so these IDs will depend on user data.
  • Example - Return records with “Example place” (example ID = 1123) as a linked place access point: /api/informationobjects?places=1123
• subjects: Returns records filtered by their association to a particular subject access point. For more information on linking an archival description to an access point, see: Add an access point “on the fly” from an archival description. Expects the internal subject term ID as a value - AtoM does not include default subject terms during installation, so these IDs will depend on user data.
  • Example - Return records with “Example subject” (example ID = 945) as a linked subject access point: /api/informationobjects?subjects=945
• genres: Returns records filtered by their association to a particular genre access point. For more information on linking an archival description to an access point, see: Add an access point “on the fly” from an archival description. Expects a specific ID for one of the terms in the Genre taxonomy as a value. AtoM includes 45 default terms at installation, taken from the US Library of Congress’ “Basic Genre Terms for Cultural Heritage Materials,” available at: http://memory.loc.gov/ammem/techdocs/genre.html.
  • Example - Return records with “Photographs” (ID = 403) as a linked genre access point: /api/informationobjects?genres=403
• creators: Returns records filtered by their association to particular actor (i.e. link to an authority record as a creator). Expects the internal actor ID as a value. AtoM does not include default authority records at installation, so these IDs will depend on user data.
  • Example - Return records linked to “Creator 1” (example ID = 1245) authority record as a creator: /api/informationobjects?creators=1245
• names: Returns records filtered by their association to particular actor (i.e. link to an authority record as a name access point). Expects the internal actor ID as a value. AtoM does not include default authority records at installation, so these IDs will depend on user data.
  • Example - Return records linked to “Name 1” (example ID = 4432) authority record as a name access point: /api/informationobjects?names=4432
• collection: Similar to the “Part of” facet in the user interface - see Using the “Part of” facet for further information. Returns records with a common top-level parent record. Expects the information object ID of the top-level parent record as its value. These IDs will depend on user data.
  • Example - Return descendent records of “Example fonds” (example ID = 972): /api/informationobjects?collection=972
• startDate: Used to supply a start date for a date range query over the event dates associated with an information object. Expects an ISO-8601 formatted date string (YYYY-MM-DD) as its value. Queries against the internal, controlled start date value associated with an archival description (not the display date, which allows users to include expressions of approximation or uncertainty in the date display). For more information, see: Date range search filter.
  • Example - Return records with a start date of 1900 or later: /api/informationobjects?startDate=1900-01-01
• endDate: Used to supply a end date for a date range query over the event dates associated with an information object. Expects an ISO-8601 formatted date string (YYYY-MM-DD) as its value. Queries against the internal, controlled end date value associated with an archival description (not the display date, which allows users to include expressions of approximation or uncertainty in the date display). For more information, see: Date range search filter.
  • Example - Return records with a end date of 1900 or earlier: /api/informationobjects?endDate=1900-01-01
• rangeType: Associated with a date range search, this parameter determines the type of date range query applied - inclusive, or exact. For more information, see: Date range search filter. When this parameter is not included with a date range query, the default value is inclusive. Accepted parameter values:
  • exact: the start and end dates of descriptions returned must fall entirely within the date range entered.
  • inclusive: any description whose start or end dates touch or overlap the target date range will be returned. Note: this is labelled as “Overlapping” in the Advanced search user interface.
  • Example - Return records whose dates of creation fall exactly between 1900 and 1902: /api/informationobjects?startDate=1900-01-01&endDate=1902-12-31&rangeType=exact

Combining boolean and filter parameters - examples¶

Return results that have the word “west” in a place access point field:

/api/informationobjects?sq0=west&sf0=place&topLod=0

Return results that have NO place access point, created between 1950 and 1969:

/api/informationobjects?sq0=_missing_:places&startDate=1950-01-01&endDate=1969-12-31&rangeType=exact&topLod=0

Return Series-level records with ANY subject access point AND tax* in the Scope and content field, sorted by most recently created or modified:

/api/informationobjects?sq0=_exists_:subjects&so1=and&sq1=tax*&sf1=scopeAndContent&levels=224&sort=lastUpdated

Return results with coffee OR chocolate in any field, with dates that match or overlap a range of January 1, 1990 - March 4, 2001, sorted by date:

/api/informationobjects?sq0=chocolate&so1=or&sq1=coffee&startDate=1990-01-01&endDate=2001-03-04&rangeType=inclusive&sort=date

Back to top