En français

ECCC logo

TdM > MSC GeoMet > OGC API

OGC API

The Open Geospatial Consortium (OGC) API standards are a set of specifications developed by the OGC to facilitate the interoperable exchange of geospatial data and services over the web. These standards are designed to enable seamless integration and sharing of geospatial information across different systems, applications, and organizations. The following documentation will go over the basics of the OGC API - Features and OGC API - Coverages standards and provide examples of how to query GeoMet-OGC-API using these standards.

Main endpoints

GET / - Landing page

https://api.weather.gc.ca/

The GeoMet-OGC-API landing page with links to view the data collections, processes, and conformance classes implemented by the API.

GET /collections - All data collections

https://api.weather.gc.ca/collections

Retrieves information describing the set of supported collections and provides a list of collections with data type and a brief description.

GET collections/{collectionID} - Collection-specific information

https://api.weather.gc.ca/collections/hydrometric-daily-mean

Retrieves descriptive information about a specific collection, either of type feature or type coverage. For example, the URL above returns the root page for the Hydrometric Monitoring Stations feature collection.

GET /openapi - OpenAPI documentation

https://api.weather.gc.ca/openapi

The API documentation links provide a Swagger page of the API as a tool for developers to provide example request/response/query capabilities. A JSON representation is also provided.

GET /conformance - API conformance definition

https://api.weather.gc.ca/conformance

The conformance page provides a list of URLs corresponding to the OGC API conformance classes supported by GeoMet-OGC-API.

Common Query Parameters

The following section provides information regarding common query parameters often used when making requests to both feature and coverage collections. Query parameters are passed with the request URL using the ? character to separate the query parameter from the URL and the & character to separate multiple query parameters.

f - Format query parameter

https://api.weather.gc.ca/collections/?f=json

The format query paremeter is used to specify the format of the server response. Depending on the collection type, the value of the format query parameter could be one of of the following: html, json. The example above returns the list of available collections from GeoMet-OGC-API as a JSON object.

For feature collections, results can also be returned as a CSV file via ?f=csv.

For coverage collections, the output format of the coverage can be specified via this parameter. Depending on the collection and its supported output formats, the following values are supported: GRIB, GTiff, and NetCDF in GeoMet-OGC-API but their support is on a per coverage collection basis.

bbox - Bounding box query parameter

https://api.weather.gc.ca/collections/aqhi-observations-realtime/items?bbox=-71,46,-65,49

Retrieves information according to a specific region or bounding box. It is a rectangular area defined by two sets of coordinates that represent the minimum and maximum extents of the box. bbox coordinate values must be fall within the bounds of EPSG:4326. The coordinates specified must be in the following order: minX, minY, maxX, maxY.

datetime - Datetime query parameter

https://api.weather.gc.ca/collections/hydrometric-daily-mean/items?datetime=1972-10-30

Retrieves information according to a specific date, year or time interval. It is highly recommend to use RFC 3339 compliant datetime strings (i.e. YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ). The datetime parameter can be used in conjunction with the .. keyword to specify a time extent. For example, datetime=2012-05-20/.. returns all items from 2015-05-20 onwards. datetime=../2015-11-11 returns all items older than 2015-11-11.

OGC API - Features

The OGC API - Features (OAFeat) standard provides a list of standardized specifications for querying vector-based geospatial data (points, lines and polygons) on the web. Listed below are example OGC-API feature collection endpoints, examples for spatial, temporal and property filtering, and further details regarding pagination.

GET collections/{collectionID}/items - Feature collection items

https://api.weather.gc.ca/collections/hydrometric-daily-mean/items

Returns items from a specified collection.

The above URL returns items from the hydrometric-daily-mean collection: Hydrometric Daily Mean Items

GET collections/{collectionID}/items/{itemID} - Single feature overview

https://api.weather.gc.ca/collections/hydrometric-daily-mean/items/01AA002

Returns the item with the corresponding ID from the requested collection and provides its full set of properties.

The above URL returns the item with ID 01AA002 from the hydrometric-stations collection: Item 01AA002

GET collections/{collectionID}/items?{query parameters} - Query a feature collection

Feature collection queries allow for spatial, temporal, and property filtering. Filter parameters can be combined to formulate a more complex query. The first parameter of a query must be specified with ? and subsequent parameters with &.

Below are a few examples of various types of queries, ranging from simple bbox and datetime filtering queries to more complex queries comprised of multiple query parameters. All queries are made to the hydometric-daily-mean feature collection.

Spatial

Query by bounding box (minx, miny,maxx, maxy).

https://api.weather.gc.ca/collections/hydrometric-stations/items?bbox=-71,46,-65,49

Returns items from the feature collection that intersect the provided bounding box: Map with selected area

Temporal

Query for an instantaneous value with a single date:

https://api.weather.gc.ca/collections/hydrometric-daily-mean/items?datetime=1972-10-30

Returns feature collection items that match the provided datetime value: Items from collection that match datetime

Query for a time interval:

https://api.weather.gc.ca/collections/hydrometric-daily-mean/items?datetime=1972-10-30/2010-07-31

Returns feature collection items that fall within the provided datetime range: Items from collection that fall within the provided datetime range

Query by time extent with the open ended .. keyword:

Property

Query by an entity collection property:

https://api.weather.gc.ca/collections/hydrometric-daily-mean/items?STATION_NUMBER=10CD001

Returns feature collection items that have STATION_NUMBER = 10CD001 Features by station number

Paging

Combining filter parameters

Query all hydrometric daily mean data from a single station between 2001 and 2010:

https://api.weather.gc.ca/collections/hydrometric-daily-mean/items?STATION_NUMBER=10CD001&datetime=2001-01-01/2010-12-31

Exporting to CSV format

Results from queries made against feature collections can be exported to the CSV format by adding &f=csv to the request, or by clicking on the CSV top-right icon on the collection page.

https://api.weather.gc.ca/collections/hydrometric-daily-mean/items?f=csv

Sorting

Results from a query can be sorted by using the sortby parameter. By default, the sort order is ascending. For a descending sort, add the - (minus) character prior to the property name. Sorting by multiple properties is supported by providing a comma-separated list of properties to the sortby query parameter.

&sortby=PROPERTY sorts the property in ascending order &sortby=-PROPERTY sorts the property in descending order.

Examples with the DATE property:

https://api.weather.gc.ca/collections/hydrometric-daily-mean/items?STATION_NUMBER=01AP004&offset=1000&limit=1000&sortby=DATE ascending

https://api.weather.gc.ca/collections/hydrometric-daily-mean/items?STATION_NUMBER=01AP004&offset=1000&limit=1000&sortby=-DATE descending

OGC API - Coverages

The OGC API - Coverages standard specifies the fundamental API building blocks for interacting with coverages (raster data). The spatial data community uses the term "coverage" to refer to homogeneous sets of values ​​located in space and time, such as data from spatiotemporal sensors, images, simulation and statistics.

GET collections/{coverageId} - Coverage collection landing page

https://api.weather.gc.ca/collections/climate:cmip5:historical:annual:anomaly

Retrieves detailed coverage metadata for the specified collection. This page displays the collections geographic extent, supported output forms and related links.

GET collections/{coverageId}/coverage - Coverage query with no parameters

https://api.weather.gc.ca/collections/climate:cmip5:historical:annual:anomaly/coverage

Retrieves the coverage data and related self-describing information (range set, domain set, range type, metadata). It is comparable to a WCS GetCoverage response. By default, the response is returned as JSON. The URL above returns the entire coverage data for the default coverage field "tas" (surface temperature).

GET collections/{coverageId}/coverage/rangetype - Coverage range type

https://api.weather.gc.ca/collections/climate:cmip5:historical:annual:anomaly/coverage/rangetype?

Returns the range type of the coverage, that is, the semantics of the data values ​​(their components and the data type). The range type response returns a list of fields that can be queried against the coverage. For example, the query below returns the range type for the CMIP5 Historical annual anomaly collection. RangeType

GET collections/{coverageId}/coverage/domainset - Coverage domain set

https://api.weather.gc.ca/collections/climate:cmip5:historical:annual:anomaly/coverage/domainset

Returns the domain of the coverage (the detailed n-dimensional space covered by the data). Domains include available axis labels, extent of coverage, pixel size, and resolution.

Domainset

GET collections/{coverageId}/coverage?{params} - Coverage with query parameters

Queries against coverage collections allow for spatial, temporal, and range type filtering against the n-dimensionsal space (domain set axes) of the coverage itself. The first parameter of a query must be specified with ? and subsequent parameters with &.

Spatial

Query by bounding box (minx, miny,maxx, maxy).

https://api.weather.gc.ca/collections/climate:cmip5:historical:annual:anomaly/coverage?f=json&bbox=-80.557251,42.561173,-75.135498,44.805224 or https://api.weather.gc.ca/collections/climate:cmip5:historical:annual:anomaly/coverage?f=json&bbox=-80.557251,42.561173,-75.135498,44.805224&f=NetCDF

Temporal

Query for an instantaneous value for a single period if a "time" axis label is available, for this specific coverage:

https://api.weather.gc.ca/collections/climate:cmip5:historical:annual:anomaly/coverage?f=json&datetime=1905

Query for a time interval:

https://api.weather.gc.ca/collections/climate:cmip5:historical:annual:anomaly/coverage?f=json&datetime=1901/1905

Rangetype field

Query for a specifc range type field with the properties query parameter. For example, the query below retrieves coverage data for the rangetype field named "sit" (sea ice thickness).

https://api.weather.gc.ca/collections/climate:cmip5:historical:annual:anomaly/coverage?properties=sit

Domain set dimension

Query by a dimension specificied in the domain set with the subset query parameter.

https://api.weather.gc.ca/collections/climate:cmip5:historical:annual:anomaly/coverage?subset=percentile(25)

Combination of filter parameters

Query the coverage with a spatial and temporal filter, for a a specific rangetype field via the properties query parameter.

Returns in json format by default:

https://api.weather.gc.ca/collections/climate:cmip5:historical:annual:anomaly/coverage?bbox=-80.557251,42.561173,-75.135498,44.805224&properties=sfcWind&datetime=1901/1905

Export to GTiff or NetCDF format

Queries pointing to collections pages can be exported in GTiff format and NetCDF format if available. Consult the root of a given coverage collection to identify the available response data formats. For example:

https://api.weather.gc.ca/collections/climate:cmip5:projected:annual:absolute?f=json

Under the links key, the available values for the ?f parameter can be found. In this case the coverage data can be requested in JSON via ?f=json or as NetCDF via ?f=NetCDF.