Canadiana API Documentation (DRAFT)

Ce document de travail n'est disponible qu'en anglais. La version finale sera disponible en français

Status

Version 0.3

The Canadiana API and this documentation is still a work in progress. Both should be considered experimental.

Synopsis

Any search query can be turned into a Web service request by appending the parameter fmt=json to retrieve a JSON object.

Results Paging

To retrieve a specific page of results from the result set, add the page number to the end of the URL. If omitted, the first page is returned:

Text Queries

For general text queries (all bibliographic metadata, abstracts, and full text) use the q parameter with one or more terms:

Search for phrases by enclosing them in quotes: "". Use * and ? as wildcard characters in the middle or at the end of a work (not phrases). Prefix a term with - to require it not be present (NOT operator). Separate terms with | to match on either term (OR operator):

Field-Limited Queries

To limit queries to a particular field, you can either prefix a term with the field name and a colon or use the feld name as a separate query parameter. Mixing and matching is also allowed:

Supported text fields include:

  • q: all text fields (including full text)
  • au: author/creator names
  • ti: titles
  • su: subject headings/keywords

Additionally, the following controlled value fields are supported:

  • contributor: contributor code
  • media: media type (text|image|audio|video|data|plaintext)
  • lang: document language (ISO 693-3 code)
  • set: index subset
  • t: record type (any|document|series|page|default - default is documents and series)
  • key: record unique key
  • pkey: record parent key

Date Range Limiting

Use the df and dt parameters to limit a result set to documents published within the given range of years:

Result Sorting

Results are sorted by relevance ranking by default. Add the parameter sort=oldest or sort=newest to sort by publication date in ascending or descending order.

Retrieving Individual Records

You can also retrieve individual item records by key:

You can choose to retrieve the full text for the record by adding the parameter api_text=1. Since some documents might have a very large amount of text (many megabytes) it is recommended that this option not be used routinely, but only where the full text is specifically desired.

Response Structure