GeoGratis (API) - Product Search
Series and Collections
Use our API to embed GeoGratis search, discovery and access functionalities into new or existing applications and services located within your own work environment. By utilizing the latest web-application standards, protocols and formats, our API aims to minimize the burden of development and maximize the re-use of GeoGratis data and information products.
End User Documentation
Note: This documentation is being revised and was adapted from: http://atomserver.codehaus.org/docs/protocol_reference.html.
The GeoGratis REST API is based on AtomServer which is a GData-style atom store. AtomServer has been enhanced to support additional filtering and indexing capabilities specific to GeoGratis.
Available content is organized into workspaces and collections. In the example below nrcan-rncan is the workspace and ess-sst is the collection:
The API (AtomServer) query parameters are summarized in the following table. All parameter values need to be URL encoded.
|Parameter Note to screen readers users: spell out items in this column letter by letter.||Meaning||Notes|
|Search terms||Example: |
Allows for spatial filtering. Must be in the form of west, south, east, north. For example: |
|Category queries||List the Category as if it were part of the resource's URI, in the form
|Bounds on the entry update date||Use the RFC 4287 timestamp format. For example: 2005-08-09T10:57:00-08:00. The lower bound is inclusive. In other words, it is used as ">= updated-min" in the resulting query. The upper bound is exclusive. In other words, it is used as "< updated-max" in the resulting query. These parameters may be applied to Entry requests, with limited meaning. A 304 NOT MODIFIED will be returned if the Entry does not fit within the bounds provided.|
|Maximum number of results to be retrieved||max-results must be |
|The type of Entry to return.||Indicates the type of Entry to return. The choices are full or link. full
causes a "full Entry" to be returned (i.e. the |
|Alternative format (aka representation)||Example: |
Most data requires categorization to make it more manageable, especially as the data grows in size. Categorization is the characterization of data into collections based on some common attribute. The Atom specification provides a built-in mechanism for categorization. Categories appear in Service Documents, where they describe the categories allowed in a Collection. The following link will return the Service Document for the nrcan-rncan workspace:
The "categories" element can contain zero or more "category" elements from the Atom namespace. A Category is simply a way to assign arbitrary attributes to an Entry. And then using these categories the User can then group Entries into arbitrary collections.
<category> has one required attribute,
term, and two optional
termidentifies the category
schemeidentifies the categorization scheme via a URI (think of this as a namespace)
labelprovides a human-readable label for display
Example Service Document:
<service> <workspace> <atom:title type="text">mib</atom:title> <collection href="nrcan-rncan/ess-sst/"> <atom:title type="text">test</atom:title> <accept>application/atom+xml;type=entry</accept> <categories> <category scheme="urn:iso:theme" term="delorme-syncline" label="Delorme Syncline"/> <category scheme="urn:iso:theme" term="moose-prairie-syncline" label="Moose Prairie Syncline"/> <category scheme="urn:iso:theme" term="landry-formation" label="Landry Formation"/> <category scheme="urn:iso:theme" term="spirit-fault" label="Spirit Fault"/> </categories> </collection> </workspace> </service>
Supported Formats (aka Representations)
Search results by default are presented as an ATOM feed. The following additional formats are available depending on the intended usage:
- Atom Feed [alt=atom]
- RSS [alt=rss]
- HTML [alt=html]
- Partial HTML [alt=phtml]
- KML [alt=kml]
- CSV [alt=csv]
- GCOD [alt=gcod]
- JSON [alt=json] - JSONP is supported also, just pass in a callback parameter.
Note these examples explicitly request a specific format but you could just as easily leave out the format extension (e.g .atom) and let content-negotiation return your clients' preferred format via the default Accept Headers.
Discovery & Access
Search results contain links to information about the products returned. This information is available in a variety of formats depending on the intended usage:
- Atom Feed [.atom]
- HTML [.html]
- Partial HTML [.phtml]
- XML [.nap] - Returns ISO Metadata
- KML [.kml]
- JSON [.json] - JSONP is supported also, just pass in a callback parameter.
Note that this is information about a product and is not a representation of the product. The following examples return metadata about a particular product that is referenced in a search result; this metadata contains links to the actual physical dataset (i.e. GIS dataset, scientific report, or tabular data).
Note these examples explicitly request a specific format but you could just as easily leave out the format extension (e.g .nap) and let content-negotiation return your clients' preferred format.
ISO Metadata (North American Profile [NAP]): http://geogratis.gc.ca/api/en/nrcan-rncan/ess-sst/6bec37c2-6e12-5812-a2a3-e949cb86d861?alt=nap
Basic Search (Google style)
To search for a data asset based on some value (i.e. "islands") simply use the "q=" syntax. For example:
Currently as implemented all data assets are full-text indexed so all data assets that have the term "islands" in any field are returned.
To search by spatial extents, use the "bbox=minx,miny,maxx,maxy" syntax with coordinates expressed in longitude (x-axis) and latitude (y-axis) in decimal degrees. For example:
Using Category Filters
Category name and values list are available in the Service Document found here: http://geogratis.gc.ca/api/en/nrcan-rncan/ess-sst/$categories
A category filter can be applied with the following syntax:
Using AND/OR operators with Categories
The following example filters on entries that are categorized as geophysics AND anomalies AND whose metadata includes the term islands.
- Date modified: