Rechercher Produits

Parcourir les produits

Parcourir par type de produits

Parcourir par série de publications

Développeurs

L'API permet aux développeurs d'incorporer, dans leur propre environnement de travail, les fonctionnalités de recherche, de découverte et d'accès offertes par GéoGratis à des applications et services qu'ils soient nouveaux ou existants. En utilisant les plus récents protocoles, normes et formats d'application Web, l'API vise à minimiser les efforts en matière de développement et à maximiser la réutilisation de données et de produits d'information de GéoGratis.

Documentation

Documentation de l’utilisateur final

Remarque : Cette documentation est en cours de révision et a été adapté à partir de: http://atomserver.codehaus.org/docs/protocol_reference.html.

L'API REST de GéoGratis est basée sur le logiciel AtomServer, qui est un entrepôt atome de style GData. AtomServer a été amélioré pour prendre en charge les capacités de filtrage et d'indexation supplémentaire qui sont spécifiques à GéoGratis.

Le contenu disponible est organisé en espaces de travail et en collections. Dans l'exemple ci-dessous, nrcan-rncan est l'espace de travail et ess-sst la collection :

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

Les paramètres de requête de l'API (AtomServer) sont résumés dans le tableau ci-dessous. Toutes les valeurs de paramètres doivent être en encodage URL.

Paramètres Note aux utilisateurs de lecteurs d'écran : préciser la lecture lettre par lettre de cette colonne.	Signification	Notes
`q`	Terme de recherche	Example: `q=rivière`. Ce paramètre peut prendre en charge plusieurs termes séparés par des espaces. Les espaces sont équivalents à l’insertion de l’opérateur ET (comme avec Google). Plus de mots clés sont fournis, moins de résultats seront trouvés.
`bbox`	Filtre spatial	Permet le filtrage spatial. La valeur du paramètre doit respecter le format suivant : ouest, sud, est, nord.. Par exemple: `bbox=-72.0,44.5,-69.5,45.5`
`/-/category`	Requêtes de catégorie	Indiquer la catégorie, comme si elle faisait partie de l'URI de la ressource, sous la forme `/-/categoryname`. Notez qu’il s'agit d'une exception à la forme de requête usuelle: `name=value`. Vous devez indiquer toutes les catégories avant tout autre paramètre de requête. Par exemple http://geogratis.gc.ca/api/fr/nrcan-rncan/ess-sst/-/(urn:gc:subject)climat
`updated-min, updated-max`	Limites sur la date de mise à jour de l’entrée	Utilisez le format d'horodatage RFC 4287. Par exemple: 2005-08-09T10:57:00-08:00. La limite inférieure est inclusive. En d'autres termes, elle est utilisée comme ">= updated-min" dans la requête résultante. La limite supérieure est exclusive. En d'autres termes, elle est utilisée comme "> updated-max" dans la requête résultante. Ces paramètres peuvent être appliqués avec une signification limitée aux requêtes pour une entrée. Un code 304 (NON-MODIFIÉ) sera retourné si la date de mise à jour de l’entrée n’est pas incluse à l'intérieur des limites fournies.
`max-results`	Nombre maximal de résultats à trouver	Le nombre maximal de résultats doit être `<=100`. Toute valeur plus grande que la limite du nombre maximal de résultats sera automatiquement ramenée è la valeur maximale.
`entry-type`	Type d’entrées retournées	Indique le type de d’entrée à rechercher. Les valeurs permises sont full ou link. L’utilisation de la valeur `full` fera en sorte que les « entrées complètes » seront retourrnées (c'est-à-dire que l’élément `<content>` contiendra l'intégralité des données XML demandées). L’utilisation de la valeur Link fera en sorte que des « entrée en lien » seront retournées (c'est-à-dire qu’aucun élément `<content>` ne sera présent). Au lieu, des liens (self et edit) seront présentés pour chacunes des entrée retournées. La valeur par défaut pour les requêtes de fils est link, tandis que la valeur par défaut pour les requêtes d’entrées est full.
`alt`	Format alternatif (représentation)	Par exemple: `alt=kml`. Différents formats sont pris en charge pour les fils et les saisies. Voir ci-dessous.

Catégories

Il peut être utile de catégoriser les données afin de les rendre plus faciles à gérer, plus particulièrement lorsque le volume de données est important. La catégorisation est une mise en relation de données basée sur le partage d’une valeur identique à l’intérieur d’un attribut commun. La spécification Atom procure un mécanisme intégré de catégorisation. Les catégories apparaissent dans les documents de service, où ils décrivent les catégories admises dans une collection. Le lien suivant renvoie au document de service pour l'espace de travail nrcan-rncan :

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

Dans ce document de service, les éléments <categories> peuvent contenir zéro ou plusieurs éléments <category> appartenant à l'espace de noms Atom. Une catégorie est simplement une façon d'assigner des attributs arbitraires à une entrée permettant ensuite à l’utilisateur peut regrouper les entrées dans des collections arbitraires.

<category> a un attribut obligatoire nommé term, et deux attributs facultatifs, scheme et label.

term identifie la catégorie
scheme identifie le système de catégorisation via un URI (semblable à un espace de noms)
label contient une étiquette humainement lisible décrivant la catégorie

Exemple de document de service :

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

Formats disponibles (représentations)

Recherche

Les résultats de recherche sont présentés par défaut dans un fil ATOM. Les formats supplémentaires suivants sont disponibles en fonction de l'utilisation prévue :

fil Atom [alt=atom]
RSS [alt=rss]
HTML [alt=html]
HTML partielle [alt=phtml]
KML [alt=kml]
CSV [alt=csv]
GCOD [alt=gcod]
JSON [alt=json] - JJSONP est aussi pris en charge, il suffit d’utiliser un paramètre de rappel nommé callback.

Exemples :

Notez que les exemples ci-dessous demandent explicitement un format spécifique, mais il est possible d’omettre l’extension du format (par exemple, .atom) et laisser la négociation de contenu identifier le format le plus approprié grâce à l’en-tête accept du protocole HTTP fourni par le client utilisé.

Fil ATOM: http://geogratis.gc.ca/api/fr/nrcan-rncan/ess-sst?max-results=100&q=iles&alt=atom

HTML: http://geogratis.gc.ca/api/fr/nrcan-rncan/ess-sst/?max-results=100&q=iles&alt=html

Découverte et accès

Les résultats de la recherche contiennent des liens vers des informations sur les produits trouvés. Ces informations sont disponibles dans une variété de formats en fonction de l'utilisation prévue :

fil Atom [.atom]
HTML [.html]
HTML partielle [.phtml]
XML [.nap] - Trouve les métadonnées ISO
KML [.kml]
JSON [.json] - JSONP est aussi pris en charge, il suffit d’utiliser un paramètre de rappel nommé callback.

Notez que ce sont des informations sur un produit et non pas une représentation du produit. Les exemples ci-dessous pointent à des métadonnées sur un produit particulier qui est référencé dans un résultat de recherche; ces métadonnées contiennent des liens vers les données réelles (c.-à-d., des données SIG, des rapports scientifiques ou des données tabulaires).

Exemples :

Notez que les exemples ci-dessous demandent explicitement un format spécifique, mais il est possible d’omettre l’extension du format (par exemple, .nap) et laisser la négociation de contenu identifier le format le plus approprié grâce à l’en-tête accept du protocole HTTP fourni par le client utilisé.

Métadonnées ISO (profil nord-américain [PAN]): http://geogratis.gc.ca/api/fr/nrcan-rncan/ess-sst/6bec37c2-6e12-5812-a2a3-e949cb86d861.nap

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

Exemple d’utilisation

Recherche de base (style Google)

Pour rechercher des données associées à un teme (par exemple « îles »), il suffit d'utiliser la syntaxe « q= ». Par exemple :

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

Dans l’implémentation actuelle, les données sont textuellement indexées afin que toutes les données qui ont le terme « îles » dans quelque section que ce soit, soient trouvées.

Recherche spatiale

Pour effectuer une recherche par étendue spatiale, utilisez la syntaxe « bbox=minx,miny,maxx,maxy » avec les coordonnées en degrés décimaux exprimées en longitude (axe des x) et en latitude (axe des y). Par exemple:

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

Utilisation des filtres de catégorie

Le nom des catégories et la liste des valeurs possibles sont présentés dans le document de service suivant: http://geogratis.gc.ca/api/fr/nrcan-rncan/ess-sst/$categories

Un filtre sur une catégorie peut être utilisé avec la syntaxe suivante :

http://geogratis.gc.ca/api/fr/nrcan-rncan/ess-sst/-/(urn:gc:subject)climat?q=érosion

Utilisation des opérateurs ET/OU avec catégories

L’exemple suivant filtre les entrées qui sont classées dans les catégories puits Et lithologie ET dont les métadonnées comprennent le terme quebec.

http://geogratis.gc.ca/api/fr/nrcan-rncan/ess-sst/-/AND/(urn:iso:type)map/(urn:gc:subject)climat?q=érosion&alt=html