TdM > GeoMet du SMC > OGC API
OGC API
Les normes API de l'Open Geospatial Consortium (OGC) sont un ensemble de spécifications développées par l'OGC pour faciliter l'échange interopérable de données et de services géospatiaux sur le web. Ces normes sont conçues pour permettre une intégration et un partage transparents des informations géospatiales entre différents systèmes, applications et organisations. La documentation suivante présente les bases des normes OGC API - Features et OGC API - Coverages et fournit des exemples d'interrogation de GeoMet-OGC-API à l'aide de ces normes.
Points d'accès principaux
GET / - Page d'accueil
https://api.meteo.gc.ca La page d'accueil GeoMet-OGC-API avec des liens pour visualiser les collections de données, les processus et les classes de conformité mises en œuvre par l'API.
GET /collections - Toutes les collections de données
https://api.meteo.gc.ca/collections
Récupère les informations décrivant l'ensemble des collections prises en charge et fournit une liste des collections avec le type de données et une brève description.
GET collections/{collectionID} - Informations spécifiques à la collection
https://api.meteo.gc.ca/collections/hydrometric-daily-mean
Récupère des informations descriptives sur une collection spécifique, soit de type entité, soit de type couverture. Par exemple, l'URL ci-dessus renvoie la page racine de la collection d'entités Stations de surveillance hydrométrique.
GET /openapi - Documentation de l'OpenAPI
https://api.meteo.gc.ca/openapi
Les liens de la documentation de l'API fournissent une page Swagger de l'API comme outil pour les développeurs afin de fournir des exemples de capacités de demande/réponse/requête. Une représentation JSON est également fournie.
GET /conformance - Définition de la conformité de l'API
https://api.meteo.gc.ca/conformance
La page de conformité fournit une liste d'URL correspondant aux classes de conformité de l'API de l'OGC supportées par GeoMet-OGC-API.
Paramètres de requête communs
La section suivante fournit des informations sur les paramètres de requête courants, souvent utilisés lors de l'envoi de requêtes aux types de collection Feature et Coverage. Les paramètres de requête sont transmis avec l'URL de la requête en utilisant le caractère ?
pour séparer le paramètre de requête de l'URL et le caractère &
pour séparer plusieurs paramètres de requête.
f - Format du paramètre de requête
https://api.meteo.gc.ca/collections/?f=json avec le format json
.
Le paramètre de requête format est utilisé pour spécifier le format de la réponse du serveur. Selon le type de collection, la valeur du paramètre de requête du format peut être l'une des suivantes : html, json. L'exemple ci-dessus renvoie la liste des collections disponibles de GeoMet-OGC-API sous forme d'objet JSON.
Pour les collections d'entités, les résultats peuvent également être renvoyés sous forme de fichier CSV via ?f=csv
Pour les collections de couverture, le format de sortie de la couverture peut être spécifié via ce paramètre. En fonction de la collection et des formats de sortie supportés, les valeurs suivantes sont supportées : GRIB
, GeoTiff
, et NetCDF
dans GeoMet-OGC-API.
bbox - Paramètre de requête pour une boîte de délimitation
https://api.meteo.gc.ca/collections/aqhi-observations-realtime/items?bbox=-71,46,-65,49
Permet d'extraire des informations en fonction d'une région spécifique ou d'une boîte de délimitation. Il s'agit d'une zone rectangulaire définie par deux ensembles de coordonnées qui représentent les extensions minimale et maximale de la boîte. Les valeurs des coordonnées bbox
doivent être comprises dans les limites de EPSG:4326. Les coordonnées spécifiées doivent être dans l'ordre suivant : minX, minY, maxX, maxY
.
datetime - Paramètre de requête de date
https://api.meteo.gc.ca/collections/hydrometric-daily-mean/items?datetime=1972-10-30
Recherche d'informations en fonction d'une date, d'une année ou d'un intervalle de temps spécifique. Il est fortement recommandé d'utiliser des chaînes de dates conformes à la norme RFC 3339 (c'est-à-dire YYYY-MM-DD
ou YYYY-MM-DDTHH:MM:SSZ
). Le paramètre datetime peut être utilisé en conjonction avec le mot-clé ..
pour spécifier une période de temps. Par exemple, datetime=2012-05-20/..
renvoie tous les éléments à partir de 2015-05-20. datetime=../2015-11-11
renvoie tous les éléments antérieurs à 2015-11-11.
OGC API - Features
La norme OGC API - Features (OAFeat) fournit une liste de spécifications normalisées pour l'interrogation de données géospatiales vectorielles (points, lignes et polygones) sur le web. Vous trouverez ci-dessous des exemples de points d'extrémité de collecte de caractéristiques OGC-API, des exemples de filtrage spatial, temporel et de propriété, ainsi que des détails supplémentaires concernant la pagination.
GET collections/{collectionID}/items - Éléments de la collection
https://api.meteo.gc.ca/collections/hydrometric-daily-mean/items
Retourne les entités spécifiques d'une collection.
L'URL ci-dessus renvoie des éléments de la collection hydrometric-daily-mean
:
GET collections/{collectionID}/items/{itemID}
Vue d'ensemble d'une seule entité
https://api.meteo.gc.ca/collections/hydrometric-daily-mean/items/01AA002
Renvoie l'élément de la collection demandée avec l'ID correspondant et fournit l'ensemble de ses propriétés.
L'URL ci-dessus renvoie l'élément avec l'ID 01AA002
de la collection stations hydrométriques
:
GET collections/{collectionID}/items?{paramètres de requête}
Interroger une collection d'entités
Les requêtes de collecte d'informations permettent de filtrer l'espace, le temps et les propriétés. Les paramètres de filtrage peuvent être combinés pour formuler une requête plus complexe. Le premier paramètre d'une requête doit être spécifié avec ?
et les paramètres suivants avec &
.
Vous trouverez ci-dessous quelques exemples de différents types de requêtes, allant de simples requêtes de filtrage bbox et datetime à des requêtes plus complexes composées de plusieurs paramètres de requête. Toutes les requêtes portent sur la collection de caractéristiques hydometric-daily-mean.
Spatial
Requête par boîte englobante (minx, miny, maxx, maxxy). https://api.meteo.gc.ca/collections/hydrometric-stations/items?bbox=-71,46,-65,49
Renvoie les éléments de la collection d'éléments qui intersectent la boîte de délimitation fournie :
Temporel
Recherche d'une valeur instantanée avec une seule date : https://api.meteo.gc.ca/collections/hydrometric-daily-mean/items?datetime=1972-10-30
Renvoie les éléments de la collection d'éléments qui correspondent à la valeur de date fournie :
Requête pour un intervalle de temps :
https://api.meteo.gc.ca/collections/hydrometric-daily-mean/items?datetime=1972-10-30/2010-07-31
Renvoie les éléments de la collection d'éléments qui se situent dans la plage de dates fournie :
Interrogez par période de temps avec le mot-clé ouvert ..
:
-
Depuis une date précise : https://api.meteo.gc.ca/collections/hydrometric-daily-mean/items?f=json&STATION_NUMBER=07DA006&datetime=2012-05-20/..
Les retours concernent les articles de la collection à partir de 2015-05-20.
-
Jusqu'à une date précise : https://api.meteo.gc.ca/collections/hydrometric-daily-mean/items?f=json&STATION_NUMBER=07DA006&datetime=../2015-11-11
Les retours portent sur des éléments de collection antérieurs au 2015-11-11.
Propriété
Interrogation par une propriété de la collection d'entités :
https://api.meteo.gc.ca/collections/hydrometric-daily-mean/items?STATION_NUMBER=10CD001
Retourne les éléments de la collection d'éléments qui ont STATION_NUMBER = 10CD001
.
Pagination
-
Offset
Le paramètre
offset
peut être utilisé pour spécifier l'enregistrement à partir duquel les caractéristiques sont extraites. La valeur par défaut est0
(première caractéristique) -
Nombre total d'entités
Le paramètre
resulttype=hits
est utilisé pour retourner le nombre d'entités trouvés dans une collection, sans retourner aucune entité de la collection. Le nombre de entitéss se trouve dans la clénumberMatched
de la réponse.https://api.meteo.gc.ca/collections/ltce-stations/items?f=json&resulttype=hits
-
Limite
Le paramètre
limit
est utilisé pour définir le nombre maximum d'entités à renvoyer dans la réponse. La taille limite de la réponse est de 10,000 entités par requête. Dans la requête suivante, une seule entité est demandée, par exemple, pour inspecter sa géométrie et ses propriétés :https://api.meteo.gc.ca/collections/hydrometric-daily-mean/items?limit=1
Renvoie un seul élément de la collection :
Les paramètres
offset
etlimit
peuvent être utilisés en tandem pour parcourir les collections d'éntités. Les exemples ci-dessous montrent comment ajuster et paginer les résultats d'une requête.-
Interroger et limiter aux éléments 1 à 100 : https://api.meteo.gc.ca/collections/hydrometric-daily-mean/items?STATION_NUMBER=10CD001&limit=100
-
Interroger et limiter aux éléments 101-200 : https://api.meteo.gc.ca/collections/hydrometric-daily-mean/items?STATION_NUMBER=10CD001&offsetx=101&limit=100
-
-
Stratégies de pagination
La stratégie de pagination est couramment utilisée pour extraire de grandes quantités de données. Par exemple, un client peut paginer par 500 entités pour parcourir l'ensemble d'un enregistrement de station, en commençant par les 500 premiers éléments et en demandant ensuite les 500 entités suivantes, jusqu'à ce que tous les éléments soient renvoyés. https://api.meteo.gc.ca/collections/hydrometric-daily-mean/items?STATION_NUMBER=01AP004&offset=0&limit=500
Les requêtes ci-dessus renvoient respectivement les 500 premiers éléments et les 500 éléments suivants. Le client peut alors simplement parcourir tous les éléments jusqu'à ce qu'il n'y ait plus d'enregistrements. Il s'agit alors de l'ensemble de l'enregistrement. Le point d'accès
/items
renvoie aussi un liennext
qui peut être utilisé pour récupérer la page suivante de résultats. Le liennext
contiendra le paramètreoffset
mis à jour pour la prochaine page de résultats.
Filtrer la liste des propriétés d'un élément interrogé
Interroger une collection d'éléments et renvoyer les caractéristiques pour lesquelles la liste des propriétés associées est limitée aux propriétés énumérées dans la valeur properties=
. Par exemple, la requête ci-dessous retourne des propriétés reliées aux observations de pression atmosphérique, au format JSON.
Combinaison de paramètres de filtre
Interroger toutes les données hydrométriques moyennes journalières d'une seule station entre 2001 et 2010 :
Exporter au format CSV
Les résultats des requêtes effectuées sur les collections d'entités peuvent être exportés au format CSV en ajoutant &f=csv
à la requête, ou en cliquant sur l'icône CSV
en haut à droite de la page de la collection.
https://api.meteo.gc.ca/collections/hydrometric-daily-mean/items?f=csv
Tri
Les résultats d'une requête peuvent être triés en utilisant le paramètre sortby
. Par défaut, l'ordre de tri est croissant. Pour un tri descendant, ajoutez le caractère -
(moins) avant le nom de la propriété. Le tri par plusieurs propriétés est possible en fournissant une liste de propriétés séparées par des virgules au paramètre de requête sortby
.
&sortby=PROPERTY
tri l'attribut par odre croissant
&sortby=-PROPERTY
tri l'attribut par odre décroissant.
Exemples avec la propriété DATE
:
OGC API - Coverages
La norme OGC API - Coverages spécifie les éléments fondamentaux de l'API pour interagir avec les couvertures (données matricielles). La communauté des données spatiales utilise le terme "couverture" pour désigner des ensembles homogènes de valeurs situées dans l'espace et dans le temps, telles que des données provenant de capteurs spatio-temporels, d'images, de simulations et de statistiques.
GET collections/{coverageId} - Page d'accueil de la collection de couvertures
https://api.meteo.gc.ca/collections/climate:cmip5:historical:annual:anomaly
Récupère les métadonnées de couverture détaillées pour la collection spécifiée. La réponse en JSON pour cette page affiche l'étendue géographique de la collection, la taille de la grille et les étendues (spatiale, temporelle et toute dimension additionnelle). La page racine de la collection présente aussi d'autres liens associés à la collection tels que le schéma de la collection (champs disponibles) et les URLs de couverture pour chaque format permis par la collection.
GET collections/{coverageId}/schema - Schéma de la couverture
https://api.meteo.gc.ca/collections/climate:cmip5:historical:annual:anomaly/schema
Récupère le schéma de la collection de couverture. Le schéma fournit une liste des champs disponibles et leurs types de données. Le schéma peut être retourné en format JSON ou HTML et peut être utilisé pour comprendre les champs disponibles des données de couverture.
GET collections/{coverageId}/coverage - Requête de couverture sans paramètres
https://api.meteo.gc.ca/collections/climate:cmip5:historical:annual:anomaly/coverage
Renvoie les données de couverture pour la collection spécifiée. La réponse inclura toutes les données disponibles de la collection, ce qui peut représenter un volume important. Il est recommandé d’utiliser des paramètres de requête pour filtrer les données retournées. Les données peuvent être retournées dans différents formats, comme CoverageJSON, GRIB ou NetCDF, selon la collection et les formats de sortie qu’elle prend en charge. Consultez les liens de la page racine de la collection pour connaître les formats disponibles.
GET collections/{coverageId}/coverage?{paramètres}
Couverture avec paramètres de requête
Les requêtes sur les collections de couvertures permettent un filtrage spatial, temporel et de l'étendue dans l'espace à n dimensions de la couverture elle-même. Le premier paramètre d'une requête doit être spécifié avec ?
et les paramètres suivants avec &
.
Spatial
Requête par boîte englobante (minx, miny, maxx, maxxy).
Temporel
-
Demande d'une valeur instantanée pour une période unique si une étiquette d'axe "temps" est disponible, pour cette couverture spécifique :
-
Demande d'un intervalle de temps : https://api.meteo.gc.ca/collections/climate:cmip5:historical:annual:anomaly/coverage?f=json&datetime=1901/1905
Champ du schéma
Requête pour un champ spécifique du schéma avec le paramètre de requête properties
. Par exemple, la requête ci-dessous permet de récupérer les données de couverture pour le champ nommé "sit" (épaisseur de la glace de mer).
https://api.meteo.gc.ca/collections/climate:cmip5:historical:annual:anomaly/coverage?properties=sit
Dimensions supplémentaires
Interrogez des dimensions supplémentaires (autres que les dimensions spatiales et temporelles, interrogées respectivement via les paramètres bbox
et datetime
) avec le paramètre de requête subset
. Les dimensions supplémentaires disponibles sont répertoriées sous la clé extent
à la racine de la collection de couverture, via la réponse JSON uniquement.
Combinaison de paramètres de filtrage
Interroger la couverture avec un filtre spatial, un filtre temporel et un filtre pour un champ spécifique via le paramètre de requête properties
.
Retourne au format json par défaut :
Exporter au format GeoTiff ou NetCDF
Les requêtes pointant vers les pages des collections peuvent être exportées au format GeoTiff et au format NetCDF s'il est disponible. Consultez la racine d'une collection de couverture donnée pour identifier les formats de données de réponse disponibles. Par exemple, la racine d'une collection de couverture donnée peut être consultée pour identifier les formats de données disponibles :
https://api.meteo.gc.ca/collections/climate:cmip5:projected:annual:absolute?f=json
Sous la clé links
, les valeurs disponibles pour le paramètre ?f
peuvent être trouvées. Dans ce cas, les données de couverture peuvent être demandées en JSON via ?f=json
ou en NetCDF via ?f=NetCDF
.