Product Search

Browse Products

Browse by Product Type

Browse by Publication Series

Developers

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.

Documentation

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:

http://geogratis.gc.ca/api/en/nrcan-rncan/ess-sst/

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
`q`	Search terms	Example: `q=river`. Supports multiple terms separated by spaces. Spaces are equivalent to using an AND (Google like). More terms you provide, less results you will get.
`bbox`	Bounding-box filter	Allows for spatial filtering. Must be in the form of west, south, east, north. For example: `bbox=-72.0,44.5,-69.5,45.5`
`/-/category`	Category queries	List the Category as if it were part of the resource's URI, in the form `/-/categoryname`. Note, this is an exception to the usual `name=value` form for Query parameters. List all categories before any other query parameters. For example http://geogratis.gc.ca/api/en/nrcan-rncan/ess-sst/-/(urn:gc:subject)climate
`updated-min, updated-max`	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.
`max-results`	Maximum number of results to be retrieved	max-results must be `<= 100`. Any value greater than 100 will be reset to 100.
`entry-type`	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 `<content>` contains the entirety of the XML data requested). link causes a "link Entry" to be returned (i.e. no `<content>` element is returned. Instead links (self and edit) are provided to the data requested. The default for Feeds is link, and the default for Entry is full.
`alt`	Alternative format (aka representation)	Example: `alt=kml`. Various formats are supported for feeds and entries. See below.

Categories

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:

http://geogratis.gc.ca/api/en/nrcan-rncan/

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 attributes, scheme and label.

term identifies the category
scheme identifies the categorization scheme via a URI (think of this as a namespace)
label provides 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

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.

Examples:

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.

ATOM feed: http://geogratis.gc.ca/api/en/nrcan-rncan/ess-sst?max-results=100&q=islands&alt=atom

HTML: http://geogratis.gc.ca/api/en/nrcan-rncan/ess-sst/-/AND/(urn:iso:type)map/(urn:gc:subject)climate?q=islands&alt=html

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).

Examples:

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

Partial HTML: http://geogratis.gc.ca/api/en/nrcan-rncan/ess-sst/6bec37c2-6e12-5812-a2a3-e949cb86d861?alt=phtml

Example Usage

Basic Search (Google style)

To search for a data asset based on some value (i.e. "islands") simply use the "q=" syntax. For example:

http://geogratis.gc.ca/api/en/nrcan-rncan/ess-sst/?q=islands

Currently as implemented all data assets are full-text indexed so all data assets that have the term "islands" in any field are returned.

Spatial Search

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:

http://geogratis.gc.ca/api/en/nrcan-rncan/ess-sst/?bbox=-124,48,-121,49

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:

http://geogratis.gc.ca/api/en/nrcan-rncan/ess-sst/-/(urn:iso:type)map/?q=islands

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.

http://geogratis.gc.ca/api/en/nrcan-rncan/ess-sst/-/AND/(urn:iso:type)map/(urn:gc:subject)climate?q=islands&alt=html