API Géoportail – Services Spécifications Fonctionnelles

Transcription

API Géoportail – Services
Spécifications Fonctionnelles
DATE : 24/06/2015
version 0.4
73 AVENUE DE PARIS, 94165 SAINT-MANDE CEDEX
ign.fr - geoportail.gouv.fr
Table des matières
Suivi du document...........................................................................................................................4
Contexte...........................................................................................................................................5
Description générale........................................................................................................................5
Objectifs de l'API Géoportail Services.......................................................................................5
Cas d'utilisation...........................................................................................................................5
Accès au paramétrage des couches WMTS / WMS / WFS / KML de la plateforme.............5
Mise en œuvre d'un formulaire de recherche, de calcul d'itinéraire.......................................6
Accès aux services d'altimétrie et de calcul de profil.............................................................6
Transformations de coordonnées en utilisant le service et les registres IGN.........................6
Couverture Fonctionnelle............................................................................................................6
Description détaillée........................................................................................................................8
Namespace..................................................................................................................................8
Découpage fonctionnel................................................................................................................8
Gp.protocols : Protocoles d'accès................................................................................................8
Accès en mode AJAX.............................................................................................................9
Cas d'utilisation..................................................................................................................9
Mise en oeuvre...................................................................................................................9
Exemples d'utilisation......................................................................................................10
Accès en mode JSONP.........................................................................................................11
Cas d'utilisation................................................................................................................11
Mise en oeuvre.................................................................................................................11
Gp.services : Accès aux services de la plateforme Géoportail..................................................14
Principe Général...................................................................................................................14
Accès au service d'autoconfiguration...................................................................................15
Mise en œuvre..................................................................................................................16
Exemples d'utilisation :....................................................................................................27
Géocodage Direct.................................................................................................................31
Mise en oeuvre.................................................................................................................31
Geocodage inverse...............................................................................................................37
Mise en oeuvre.................................................................................................................37
Autocomplétion....................................................................................................................42
Mise en oeuvre.................................................................................................................42
Exemples d'utilisations....................................................................................................44
Calcul d'itinéraires................................................................................................................45
Mise en œuvre..................................................................................................................45
Calcul d'isochrones / isodistances........................................................................................48
Mise en œuvre..................................................................................................................48
1/94
Services d'altimétrie.............................................................................................................51
Mise en œuvre..................................................................................................................51
Service WCTS : connaître le domaine de validité d'un Système de coordonnées...............55
Mise en œuvre..................................................................................................................55
Service WCTS : transformer des coordonnées.....................................................................57
Mise en œuvre..................................................................................................................57
Gp.formats : Gestion des formats relatifs aux services.............................................................59
Packaging..................................................................................................................................59
Annexes.........................................................................................................................................60
Principe du filtre JSONP...........................................................................................................60
Principe de l'auto-configuration................................................................................................61
Accès au service :............................................................................................................61
1ère opération :...........................................................................................................61
2ème opération :..........................................................................................................62
Réponse du service :........................................................................................................62
Mise en cache des informations..................................................................................63
Structure des données :...............................................................................................63
Schéma des données renvoyées par le service............................................................66
Service de Géocodage...............................................................................................................68
Géocodage Direct.................................................................................................................68
Géocodage inverse...............................................................................................................70
Service d'Autocomplétion.........................................................................................................72
Service de calcul altimétrique...................................................................................................74
Principe du service de calcul altimétrique............................................................................74
Détermination de l'altitude d'un ou plusieurs points........................................................74
1. Accès au service......................................................................................................74
2. Paramètres en entrée...............................................................................................74
3. Structure de la requête............................................................................................76
4. Paramètres en sortie...............................................................................................77
5. Messages d'erreur....................................................................................................79
Détermination du profil altimétrique d'une courbe..........................................................79
1. Accès au service......................................................................................................79
2. Paramètres en entrée...............................................................................................79
3. Structure de la requête............................................................................................79
4. Paramètres en sortie...............................................................................................80
Modèle de données du service altimétrique.....................................................................81
Service de calcul d'itinéraires....................................................................................................82
Syntaxe, protocoles d'accès..................................................................................................82
Données................................................................................................................................82
Requête............................................................................................................................82
Réponse............................................................................................................................83
Service de calcul d'isochrones / isodistances............................................................................86
Données................................................................................................................................86
Requête............................................................................................................................86
2/94
Réponse............................................................................................................................87
Service de transformations de coordonnées (WCTS)...............................................................89
Processus GetValidityArea...................................................................................................89
Requête............................................................................................................................89
Réponse............................................................................................................................90
Processus TransformCoordinates.........................................................................................90
Requête............................................................................................................................90
Réponse............................................................................................................................91
3/94
Suivi du document
Date
Version
24/06/2015
0.4
Raison
Version de publication pour avis
4/94
Contexte
La version 3 de l'API Géoportail doit se décliner selon une offre logicielle à trois niveaux :
1. Un premier niveau qui couvre l'accès aux référentiels Géoportail et prend en charge l'accès aux
services spécifiques de la plateforme Géoportail indépendamment de toute bibliothèque
cartographique.
2. Un second niveau qui intègre le premier et propose des intégrations des services de la platforme
Géoportail (spécifiques ou standards) dans les bibliothèques du marché via leurs mécanismes
propres d'extension. Des lots de composants graphiques peuvent être aussi proposés pour chacune
des bibliothèques supportées, déclinés selon une identité visuelle commune.
3. Un troisième niveau (« haut niveau ») qui intègre les deux niveaux précédents et offre une
solution « clef en main » d'intégration d'une carte dans une page web en s'appuyant sur une ou
plusieurs bibliothèques du marché prises sur étagère.
L'API Géoportail « Services », objet de ces spécifications, a pour but la mise en œuvre du premier
niveau.
Description générale
Objectifs de l'API Géoportail Services
L'API Géoportail Services est une brique logicielle mise à disposition des développeurs pour leur
faciliter l'accès aux services de la plateforme Géoportail. Pour cela, elle propose un ensemble de
classes et fonctions permettant :
•
d'accéder aux définitions et paramétrages des webs services de la plateforme Géoportail
ainsi qu'aux ressources accessibles depuis une clef d'accès à la plateforme.
•
d'utiliser les webservices spécifiques de la plateforme en faisant abstraction des protocoles
de dialogue.
Cas d'utilisation
Accès au paramétrage des couches WMTS / WMS / WFS / KML de la plateforme
Un développeur souhaite afficher des couches WMTS, WMS, WFS ou KML diffusées par la
platforme Géoportail à l'aide d'une bibliothèque cartographique du marché (Google, Leaflet,
OpenLayers, …).
Il dispose d'une clef d'accès à la plateforme.
Il a besoin de connaître le paramétrage à appliquer pour afficher ces couches (URL, layers,
pyramides, … ).
Le service d'autoconfiguration de la plateforme Géoportail permet d'obtenir ces informations.
L'API Géoportail Services doit permettre d'invoquer simplement ce service, d'analyser la réponse
de façon à proposer les informations lues de façon simple, intuitive et exploitable.
5/94
Mise en œuvre d'un formulaire de recherche, de calcul d'itinéraire
Un développeur souhaite proposer un formulaire HTML permettant d'intéragir avec les services de
Géocodage et de calcul d'itinéraire, indépendamment de toute visualisation cartographique.
L'internaute saisit, avec l'aide du service d'autocomplétion, des adresses ou toponymes pour établir
ses points de départ, intermédiaires et d'arrivée. Il soumet son formulaire et la page lui retoune une
feuille de route.
Les services de Géocodage, d'autocomplétion et de calcul d'itinéraire sont sollicités.
L'API Géoportail Services doit permettre de faire intéragir simplement le formulaire avec ces
services en formalisant et envoyant les requêtes OpenLS ou d'autocomplétion correspondantes à la
saisie, puis en analysant les réponses de façon à en restituer le contenu de façon simple, intuitive et
exploitable.
Accès aux services d'altimétrie et de calcul de profil
Un développeur souhaite pouvoir déterminer les altitudes en un ou plusieurs points saisis à partir
d'une interface cartographique quelquonque de façon à pouvoir soit les afficher lors de la saisie, soit
afficher un profil altimétrique à l'aide d'une bibliothèque tierce dédiée.
Les services d'altimétrie et de calcul de profil de la plateforme Géoportail sont sollicités.
L'API Géoportail Services doit permettre de formaliser et d'envoyer les requêtes à ces services puis
d'en analyser les réponses de façon à en restituer le contenu de façon simple, intuitive et exploitable.
Transformations de coordonnées en utilisant le service et les registres IGN
Un développeur souhaite transformer des lots de coordonnées pour son application en s'appuyant
sur le registre de système de coordonnées IGN (« IGNF ») et sans utiliser de bibliothèque logicielle
tierce.
Le service WCTS de la plateforme Géoportail est sollicité.
L'API Géoportail Services doit permettre de formaliser et d'envoyer les requêtes de transformation à
ce service puis de récupérer les coordonnées transformées, de façon simple, intuitive et exploitable.
Couverture Fonctionnelle
L'API Géoportail Services doit permettre d'encapsuler l'accès aux webservices suivants de la
plateforme :
* Autoconfiguration
* Géocodage
* Autocomplétion
* Calcul d'itinéraire et d'isochrones / isodistances
* Services d'altimétrie et de calcul de profils altimétriques
* Transformations de coordonnées
Au travers de l'accès au service d'autoconfiguration, l'API Géoportail Services permet de consulter
les droits relatifs à une clef (Ressources disponibles) et de disposer des paramètres nécessaires pour
exploiter ces ressources avec des outils logiciels tiers.
Elle doit permettre aussi de prendre en charge les différents protocoles d'interrogation des services
6/94
offerts par la plateforme Géoportail.
7/94
Description détaillée
Namespace
Le namespace lié à l'API Géoportail Services est « Gp ».
Découpage fonctionnel
L'API Géoportail Services se décompose en trois blocs fonctionnels :
* un bloc de gestion des protocoles d'accès aux services, accessible derrière le package
« Gp.protocols » ;
* un bloc de gestion de l'accès aux services (interrogation des services), regroupé dans le package
« Gp.services » ;
* un bloc de gestion des formats relatifs aux services (exploitation des réponses brutes des services
pour les restituer dans les formats offerts par l'API), disponible derrière le package « Gp.formats ».
Les dépendances entre ces blocs sont les suivantes :
Gp.services
dépend de
Gp.protocols
Gp.formats
Gp.protocols : Protocoles d'accès
Les webservices de la plateforme Géoportail sont, par définition, accessibles via le protocole HTTP.
Le dialogue avec ces services depuis une API cliente peut donc naturellement se faire en mode
AJAX (via des objets de type XMLHTTPRequest1 : « XHR ») en s'exposant alors aux blocages des
navigateurs due à la politique sécuritaire dite de « même origine »2 empêchant l'accès à des
ressources hébergées sur un serveur ayant un autre nom de domaine que celui où est hébergée la
page web.
La plateforme Géoportail offre aussi la possibilité de dialoguer avec les services en mode JSONP3
afin de contourner ce blocage. Le principe du protocole JSONP mis en œuvre sur la platforme
Géoportail est détaillé en annexes.
L'API Géoportail « Services » offrira donc les outils permettant de dialoguer avec les services de la
platforme selon ces deux modes.
1
2
3
cf. http://fr.wikipedia.org/wiki/XMLHttpRequest
« Same-origin policy » : http://en.wikipedia.org/wiki/Same-origin_policy
cf. http://en.wikipedia.org/wiki/JSONP
8/94
Remarque : Les utilisateurs de l'API Géoportail Services auront rarement besoin d'utiliser
directement les outils exposés ici. Ces derniers ont surtout pour vocation à être exploités par la
couche supérieure exposée dans le package Gp.services.
Accès en mode AJAX
Il s'agit de proposer une couche logicielle permettant la mise en œuvre du mode AJAX (XHR) pour
l'invocation des services de la plateforme Géoportail grâce aux navigateurs usuels.
Cette couche logicielle devra instancier la requête en fonction des paramètres passés par
l'utilisateur, l'envoyer au serveur et retourner sa réponse en paramètre d'une fonction de rappel.
L'utilisation du protocole XHR se fera toujours en mode asynchrone : les appels aux services en
mode AJAX ne bloqueront pas le déroulement de l'application.
Cas d'utilisation
L'utilisateur est un développeur qui souhaite invoquer un service de la plateforme Géoportail en
HTTP GET ou POST avec des paramètres d'appel au service et en traiter la réponse au moyen d'une
fonction de rappel.
Il doit fournir les paramètres nécessaires à l'invocation du service et la fonction de traitement de la
réponse lorsque celle-ci arrive. La couche XHR se chargera simplement d'invoquer le service en
mode AJAX et d'appeler la fonction de rappel lors de la réception du résultat. Elle offrira aussi une
possibilité de traitement en cas de non réponse du service (timeOut) au bout d'un laps de temps
paramétrable.
Mise en oeuvre
L'utilisation se fera par l'appel d'une fonction statique :
Gp.protocols.XHR(options)
Cette fonction envoie une requête HTTP sur l'URL fournie via le paramètre « options.url » en
mettant en œuvre le protocole XHR.
Elle permet de lier l'émission de la requête à deux fonctions de rappel fournies par l'utilisateur :
•
•
onResponse(result) : appelée lors de la réception des résultats avec pour paramètre la
réponse du service ;
onTimeOut() : appelée en cas de non réponse au bout d'un temps déterminé par le paramètre
« options.timeout ».
Les propriétés de l'objet « options » sont les suivantes :
Paramètre
Type
Opt.
Valeur
url
String
obligatoire
URL à invoquer.
httpMethod
String
optionnel
Méthode de transfert : "GET" ou "POST".
La valeur par défaut est "GET".
content
String
optionnel
Contenu de la requête en HTTP POST.
Si httpMethod vaut « GET », ce paramètre est ignoré.
headers
Object
optionnel
Liste d'en-têtes pour la requête HTTP.
9/94
Paramètre
Type
Opt.
Valeur
Exemple :
headers : {
'content-type' : 'text/xml'
}
timeOut
Entier positif
optionnel
Nombre de ms au bout duquel on considère que le service
n'a pas répondu.
Par défaut, cette valeur est fixée à 10000 (10 secondes).
Une valeur de 0 pour ce paramètre permet de désactiver la
gestion du timeOut.
onResponse
Fonction
Obligatoire
Fonction qui sera appelée lors de la réception des résultats
du service.
Elle prend en paramètre la réponse du service sous la forme
d'une chaîne de caractères.
onTimeOut
Fonction
optionnel
Fonction qui sera appelée en cas de non réponse du service.
Le temps au bout duquel on considère que le service n'a pas
répondu est déterminé par le paramètre timeOut.
Par défaut, une fonction timeOut, notifiant dans la console le
timeOut sur le service sera appelée.
Exemples d'utilisation
Requête en POST sur le service de géocodage du Géoportail. Utilisation d'un proxy pour contourner
les problèmes de cross-domain.
Gp.protocols.XHR({
url :"http://localhost/proxy.php?url=http
%3A//wxs.ign.fr/CLE_API/geoportail/ols%3F%0A",
method :"POST",
content :"<RequestHeader sessionID="" srsName="epsg:4326"/><Request
maximumResponses="30" methodName="GeocodeRequest" version="1.2"
requestID=""><GeocodeRequest returnFreeForm="false"><Address
countryCode="StreetAddress">StreetAddress><Building number="36"/><Street>rue
gérald rey</Street></StreetAddress><Place
type="Municipality">arles</Place><PostalCode>13200</PostalCode><Department>13</
Department><gml:envelope><gml:pos>43.682765684094534
4.604832911570827</gml:pos><gml:pos>43.686676004569826
4.614145541270513</gml:pos></gml:envelope></Address></GeocodeRequest></Request>
",
timeout : 15000,
onResponse: function (response){
console.log(response);
var parser = new DOMParser() ;
var xmlDoc = parser.parseFromString(response,'text/xml') ;
//exploitation du document XML résultat
//...
},
onTimeOut : function (){
alert("TIME OUT");
}
}) ;
10/94
Accès en mode JSONP
Il s'agit de proposer une couche logicielle permettant la mise en œuvre du protocole JSONP pour
l'invocation des services de la plateforme qui le supportent. Cette couche logicielle devra écrire la
balise <script> ayant comme valeur pour l'attibut href, l'URL du service contenant les paramètres
fournis et y rajouter, si nécessaire, le paramètre permettant l'activation du filtre au niveau de la
plateforme Géoportail (callback=xxx).
Cas d'utilisation
L'utilisateur est un développeur qui souhaite invoquer un service de la plateforme Géoportail en
HTTP GET avec des paramètres d'appel au service et en traiter la réponse au moyen d'une fonction
qui a été au préalable écrite.
Il doit fournir les paramètres nécessaires à l'invocation du service et la fonction de traitement de la
réponse lorsque celle-ci arrive. La couche JSONP se chargera simplement d'appeler cette fonction
lors de la réception du résultat. Elle offrira aussi une possibilité de traitement en cas de non réponse
du service (timeOut) au bout d'un laps de temps paramétrable.
Mise en oeuvre
Gp.protocols.JSONP(options) ;
Cette fonction réalise l'appel du service fourni via le paramètre « options.url » en mettant en œuvre
le protocole JSONP.
Elle permet de lier l'appel du service à deux fonctions de rappel fournies par l'utilisateur :
• onResponse(result) : appelée lors de la réception des résultats avec pour paramètre le
résultat du service encapsulé dans sa coquille JSON ;
• onTimeOut() : appelée en cas de non réponse du service au bout d'un temps déterminé via le
paramètre timeout.
Paramètres
Paramètre
Type
Opt.
Valeur
url
String
obligatoire
URL du service à invoquer (indépendamment du protocole
JSONP). Cette URL contient déjà les paramètres du service.
Si le paramètre dédié à la mise en œuvre du protocole
JSONP (callback=xxx) n'est pas présent, ils est rajouté par la
fonction ; sa valeur est déterminée en fonction du paramètre
callbackName.
L'ajout du paramètre output=json si nécessaire est à la
charge du développeur.
timeOut
Entier positif
optionnel
Nombre de ms au bout duquel on considère que le service
n'a pas répondu.
Par défaut, cette valeur est fixée à 10000 (10 secondes).
Une valeur de 0 pour ce paramètre permet de désactiver la
gestion du timeOut.
callbackName
String
optionnel
Valeur du paramètre callback à rajouter sur l'URL.
Si l'URL fournie contient déjà le paramètre callback, le
paramètre callbackName ne sera pas pris en compte.
La fonction de callback est créée dynamiquement par la
11/94
Paramètre
Type
Opt.
Valeur
fonction JSONP ; elle a deux fonctions : elle annule la
condition de timeOut puis appelle la fonction fournie par
l'utilisateur via le paramètre onResponse.
Par défaut, le nom de la fonction de callback sera TODO :
nom de la fonction
onResponse
fonction
Conditionnel
Nom de la fonction qui sera appelée lors de la réception des
résultats du service.
Ce paramètre sera ignoré si l'URL contient déjà le paramètre
callback. La fonction de rappel appelée sera alors celle ayant
pour nom la valeur de ce paramètre.
onTimeOut
fonction
optionnel
Nom de la fonction qui sera appelée en cas de non réponse
du service. Le temps au bout duquel on considère que le
service n'a pas répondu est déterminé par le paramètre
timeOut.
Par défaut, une fonction timeOut, notifiant dans la console le
timeOut sur le service sera appelée.
Exemple 1 : envoi d'une requête de géocodage en GET et JSONP. L'ajout du paramètre output=json
dans l'URL entraine l'encapsulation de la réponse du service dans une « coquille » JSON.
Gp.protocols.JSONP({
url :"http://wxs.ign.fr/CLE_API/geoportail/ols?xls=%3CRequestHeader
%20sessionID%3D%22%22%20srsName%3D%22epsg%3A4326%22/%3E%3CRequest
%20maximumResponses%3D%2230%22%20methodName%3D%22GeocodeRequest%22%20version%3D
%221.2%22%20requestID%3D%22%22%3E%3CGeocodeRequest%20returnFreeForm%3D%22false
%22%3E%3CAddress%20countryCode%3D%22StreetAddress%22%3EStreetAddress%3E
%3CBuilding%20number%3D%2236%22/%3E%3CStreet%3Erue%20g%E9rald%20rey%3C/Street
%3E%3C/StreetAddress%3E%3CPlace%20type%3D%22Municipality%22%3Earles%3C/Place%3E
%3CPostalCode%3E13200%3C/PostalCode%3E%3CDepartment%3E13%3C/Department%3E%3Cgml
%3Aenvelope%3E%3Cgml%3Apos%3E43.682765684094534%204.604832911570827%3C/gml
%3Apos%3E%3Cgml%3Apos%3E43.686676004569826%204.614145541270513%3C/gml%3Apos%3E
%3C/gml%3Aenvelope%3E%3C/Address%3E%3C/GeocodeRequest%3E%3C/Request%3E%0A
%0A&output=json",
timeOut : 15000,
console.log(response);
var parser = new DOMParser() ;
// la réponse xml est accessible via response.xml
var xmlDoc = parser.parseFromString(response.xml,'text/xml') ;
//exploitation du document XML résultat
//...
},
alert("TIME OUT");
}
}) ;
Exemple 2 : envoi d'une requête d'altimétrie en GET et JSONP.
url :"http://wxs.ign.fr/CLE_API/alti/rest/elevation.json?lon=0.2367|
2.1570&lat=48.0551|46.6077",
12/94
timeOut : 5000,
console.log(response.elevations);
// exploitation de la réponse
// ...
},
alert("TIME OUT");
}
}) ;
Exemple 3 : Même traitement que précédemment mais avec utilisation du paramètre « callback »
dans l'URL. Ici, le paramètre onResponse n'est pas utilisé, mais la valeur du paramètre callback doit
faire référence à une fonction existante.
function traiteResultats (response){
console.log(response.elevations);
// exploitation de la réponse
// ...
} ;
url :"http://wxs.ign.fr/CLE_API/alti/rest/elevation.json?lon=0.2367|
2.1570&lat=48.0551|46.6077&callback=traiteResultats",
timeOut : 5000,
alert("TIME OUT");
}
}) ;
13/94
Gp.services : Accès aux services de la plateforme Géoportail
On traite ici de la couche logicielle qui gère l'accès aux services de la plateforme Géoportail qui
rentent dans la couverture fonctionnelle de ce document.
Principe Général
L'API Géoportail « Services » offre pour chaque service une ou plusieurs fonctions qui permettent
d'émettre des réquêtes, de réceptionner les réponses afin de pouvoir les exploiter.
Pour un service donné, l'utilisation de l'API se fera au travers d'une fonction statique dédiée ayant la
signature globale suivante :
Gp.services.serviceOperation(options) ;
Où :
•
« serviceOperation » correspond à l'opération du service que l'on veut invoquer (geocode,
reverseGeocode, autocomplete, …) : les fonctions correspondantes seront détaillées dans les
paragraphes suivants selon les webservices traités ;
•
« options » est un objet javascript dont les propriétés sont les suivantes :
Paramètre
Type
Opt.
Valeur
apiKey
String
Conditionnel
ou
Array(String)
Clef d'accès à la plateforme Géoportail, nécessaire pour
franchir la couche de contrôle des accès pour avoir une réponse
du service invoqué.
Dans le cas de l'invocation du service d'autoconfiguration,
plusieurs clefs peuvent être passées.
Si ce paramètre n'est pas renseigné, alors le paramètre
serverUrl doit être renseigné (comprenant alors, si nécessaire la
clef API).
serverUrl
String
URL d'accès au service.
Permet de forcer l'utilisation d'un service équivalent déployé
derrière une éventuelle autre URL d'accès.
Si ce paramètre est renseigné alors, le paramètre apiKey est
ignoré.
Conditionnel
Paramètres optionnels permettant de jouer sur le protocole d'accès au service
protocol
String
Optionnel
Le protocole à utiliser pour récupérer les informations du
service d'auto-configuration : peut valoir 'JSONP' ou 'XHR'.
Par défaut, c'est le protocole JSONP qui sera utilisé.
proxyURL
String
Optionnel
Le proxy à utiliser pour pallier au problème de cross-domain
dans le cas d'une requête XHR.
Utile si le paramètre 'protocol' vaut 'XHR', il ne sera pas pris en
compte si protocol vaut 'JSONP'.
14/94
Paramètre
Type
Opt.
Valeur
httpMethod
String
Optionnel
La méthode HTTP à utiliser dans le cas d'une requête XHR :
peut valoir 'GET' ou 'POST'.
Non pris en compte si 'protocol' vaut JSONP qui fonctionne
obligatoirement en GET.
Par défaut, c'est la méthode GET qui est utilisée.
timeOut
Number
Optionnel
Délai d'attente maximal (en ms) de la réponse du service (à
partir de l'envoi de la requête). Par défaut, aucun timeOut n'est
pris en compte (timeOut= 0).
rawResponse
Boolean
Optionnel
Indique si l'on souhaite que la réponse du service ne soit pas
parsée par l'API avant d'être restituée. (Cf. paramètre
« onSuccess » pour plus de détails).
Fonction
Optionnel
Fonction appelée lorsque le service répond correctement à la
requête :(code HTTP 200, sans message d'erreur).
Fonctions de rappels
onSuccess
Cette fonction prend en paramètre la réponse du service, soit
sous la forme d'un Object Javascript formaté par le parseur
dédié à la syntaxe du service (comportement par défaut) ; soit
brute au format String non prétraité si le paramètre
« rawResponse » a été précisé avec la valeur « true ».
onFailure
Fonction
Optionnel
Fonction appelée lorsque le service ne répond pas correctement
(code HTTP de retour différent de 200 ou pas de réponse).
Paramètres spécifiques à l'invocation du service :
Ces paramètres seront détaillés service par service dans les parties suivantes
propriété
…
…
...
Exemple 1 : invocation classique d'un service avec une clef API :
Gp.services.serviceOperation({
apiKey : 'CLEF_API',
onSuccess : function(response) {
// exploitation de la reponse...
console.log(response) ;
(...)
}
}) ;
Accès au service d'autoconfiguration
Il s'agit de proposer une couche logicielle permettant d'utiliser le service d'auto-configuration des
API dont le principe est expliqué en Annexes. Cette couche logicielle devra envoyer une requête au
service d'auto-configuration, avec les paramètres éventuellement fournis, puis parser la réponse du
service, pour finalement construire une variable globale contenant les informations utiles pour
15/94
l'utilisation de l'API (configuration des services, informations sur les couches, etc.).
Cas d'utilisation
L'utilisateur est un développeur web qui souhaite initialiser sa fenêtre cartographique, et a donc
besoin d'informations sur les couches et services Géoportail disponibles avec sa clé de contrat API
(paramètres des couches, territoires, pyramides d'images, etc), sur les paramètres de configuration
par défaut (configuration de la carte, territoires, couches par défaut), ou autres informations
renvoyées par le service d'auto-configuration.
L'utilisateur peut fournir des paramètres optionnels, comme sa ou ses clés de contrat API, la
fonction de rappel à lancer en cas de succès de la récupération de l'auto-configuration, le protocole à
utiliser, ou encore l'identifiant d'une couche agrégée dont il souhaite plus d'informations concernant
l'agrégation. (voir ci-dessous pour une liste plus détaillée)
En retour, sauf si une des clés fournies est invalide, il récupère un objet JSON contenant les
informations utiles à l'utilisation de l'API ou des services Géoportail.
Mise en œuvre
L'utilisation se fera par l'appel de la fonction statique :
Gp.services.getConfig(options)
Dans un premier temps, cette fonction envoie une requête HTTP au service d'auto-configuration, via
le protocole JSONP ou Ajax, avec les éventuels paramètres fournis par l'utilisateur (clé(s) et
identifiant d'un agrégat), et et en spécifiant une fonction de callback.
Dans un second temps, après avoir récupéré la réponse XML sous forme d'un objet document, la
fonction va récupérer les différentes informations présentes dans cet objet, et les stocker selon leur
valeur dans une variable globale Gp.Config.
La fonction prend en paramètre d'entrée un objet dont les propriétés peuvent prendre les valeurs
suivantes (en plus des propriétés générales décrites précédemment) :
Paramètre
layerId
Type
String
Opt.
Optionnel
Valeur
Le nom de l'agrégat (couche) dont on veut connaître les
informations détaillées.
La présence de cette propriété implique l'utilisation de la
deuxième opération du service pour accéder aux informations
d'une couche aggrégée.
Dans ce cas, la fonction effectuera quand même dans un
premier temps la récupération des informations de l'autoconfiguration complète, sauf si un premier appel à l'autoconf a
déjà été fait avec cette clé (i.e. si la variable globale est définie
pour la clé de contrat). Elle ira ensuite chercher les
informations des couches agrégées, qui seront ajoutées à la
variable globale Gp.Config.
Paramètres de la fonction onSuccess
16/94
Paramètre
Gp.Config
Type
Object
Opt.
Valeur
Obligatoire
Il s'agit de la variable globale contenant les informations
utiles récupérées via le service d'auto-configuration. Sa
structure est détaillée ci-après.
Paramètres de la fonction onFailure :
La fonction onConfFailure prend en paramètre un objet contenant les propriétés suivantes :
Paramètre
Type
Opt.
Valeur
status
Number
obligatoire
Code HTTP de retour du serveur, ou -1 (par exemple) si
on est en timeout.
(S'il vaut 200, c'est que l'erreur provient de la lecture des
paramètres de la réponse.)
message
String
obligatoire
Message de retour du serveur, ou notification de
timeOut, ou encore de l'API en cas de problème
d'interprétation des résultats.
Résultat en sortie :
Le résultat est une variable globale Gp.Config, qui est un objet contenant les informations utiles
renvoyées par l'auto-configuration, et dont la structure est la suivante :
Gp.Config
> generalOptions
> apiKeys
> title
> BBOX
> defaultGMLGFIStyle
> theme
> windowHeight
> windowWidth
> WGS84Resolutions
> Layers
> layerID
> queryable
> hidden
> name
> title
> description
> quicklookURL
> apiKeys
> minZoomLevel
> maxZoomLevel
> BBOX
> temporalExtent
> Order
> serviceParams
> type
> serviceUrl
> version
> TileMatrixSetLink
> projection
> AdditionalSRS
17/94
> featurePrefix
> typename
> featureNS
> geometryName
> metadata
> format
> url
> xlinkType
> styles
> name
> title
> current
> legends
> format
> url
> maxScale
> xlinkType
> originators
> name
> attribution
> logo
> url
> bounds
> minZoomLevel
> maxZoomLevel
> thematics
> inspire (boolean)
> name
> formats
> current (boolean)
> name
> dimensions
> type
> visibilityRange
> visibilityMode
> noDataValue
> geometricType
> contraints
> CRS
> BBOX
> minZoomLevel
> maxZoomLevel
> temporalExtent
> aggregationOptions
> IsAggregate
> aggregatedLayers
> layerID
> layerID
> LayerID
> Territories
> territoryID
> isDefault
> defaultCRS
> additionalCRS
> additionalCRSID
18/94
> additionalCRSID
> geoBBOX
> geoCenter
> defaultOptions
> defaultZoomLevel
> minZoomLevel
> maxZoomLevel
> defaultLayers
> layerID
> layerID
> territoryID
> TileMatrixSets
> TMSID
> projection
> nativeResolutions
> matrixIds
> matrixId
> matrixHeight
> matrixWidth
> scaleDenominator
> tileHeight
> tileWidth
> topLeftCorner
> TMSID
> Projections
> CRSID
> CRSID
> Services
> serviceID
> title
> serverUrl
> version
> serviceID
Les tableaux ci-dessous détaillent les différentes propriétés de cet objet.
Propriétés de l'objet Gp.Config :
Propriété
Type
Opt.
Valeur
generalOptions
Object
Obligatoire
Options générales par défaut
layers
Object
Obligatoire
Objet ayant pour propriétés les identifiants des couches
disponibles d'après le contrat API.
territories
Object
Obligatoire
Objet ayant pour propriétés les identifiants des
territoires disponibles.
tileMatrixSets
Object
Optionnel
Objet ayant pour propriétés les identifiants des
TileMatrixSets disponibles.
projections
array({String})
Obligatoire
Tableau contenant les identifiants des projections
disponibles.
services
Object
Obligatoire
Objet ayant pour propriétés les identifiants des services
disponibles.
Propriétés de l'objet generalOptions :
19/94
Propriété
Type
Opt.
Valeur
apiKeys
Object
Obligatoire
Objet contenant les informations de la ou des clés de
contrat API spécifiées (peut être vide).
title
String
Obligatoire
Titre du service d'auto-configuration
bbox
Object({left,right,t Obligatoire
op,bottom})
Objet contenant les coordonnées correspondant à
l'étendue spatiale des données par défaut, en
coordonnées géographiques WGS84
defaultGMLGFIStyle
String
Obligatoire
URL pointant vers la feuille de style XSL (eXtensible
Stylesheet Language)
theme
String
Obligatoire
Thème par défaut
windowHeight
Float
Obligatoire
Hauteur de la fenêtre par défaut
windowWidth
Float
Obligatoire
Largeur de la fenêtre par défaut
wgs84Resolutions
Array({float})
Obligatoire
Les résolutions en WGS84. Peuvent être utiles par ex.
car les BBOX et centres des territoires sont exprimés en
coordonnées géographiques.
Propriétés des différentes couches de l'objet layers :
L'objet LAYERS a pour propriétés l'ensemble des identifiants des ressources disponibles, par
exemple : « GEOGRAPHICALGRIDSYSTEMS.MAPS$GEOPORTAIL:OGC:WMTS ». Pour chacune
d'elles, les propriétés associées sont détaillées ci-dessous :
Propriété
Type
Opt.
Valeur
name
String
Obligatoire
Le nom usuel de la couche (par exemple
« GEOGRAPHICALGRIDSYSTEMS.MAPS »)
title
String
Obligatoire
Le titre de la couche (par exemple « Cartes IGN »)
description
String
Obligatoire
La description associée à la couche
queryable
Boolean
Optionnel
On peut faire un getFeatureInfo sur la couche (WMS ou
WMTS)
hidden
Boolean
Optionnel
Par défaut la couche n'est pas visible.
quicklookURL
String
Optionnel
Url pointant vers l'image d'aperçu rapide (pour les
couches associées à une visualisation)
apiKeys
Array({String})
Optionnel
La (ou les) clé(s) de contrat à laquelle cette couche est
associée
minZoomLevel
Number
Optionnel
Le zoom minimum spécifié par défaut pour cette
couche.
maxZoomLevel
Number
Optionnel
Le zoom maximum spécifié par défaut pour cette
couche.
bbox
op,bottom})
Objet contenant les coordonnées des extrémités de
l'étendue spatiale de la couche,
en coordonnées
géographiques WGS84
temporalExtent
array({string})
Tableau contenant deux dates sous forme de chaines de
caractères, correspondant aux extrémités de l'étendue
temporelle des données : [minT, maxT].
/!\ Peu d'informations sur la signification de ces deux
Obligatoire
20/94
Propriété
Type
Opt.
Valeur
dates.
order
number
Optionnel
Utile pour ordonner les différentes couches, mais /!\
c'est un paramètre qui n'est souvent pas spécifié dans
l'entrepôt. Amélioration envisageable pour GPP4.
serviceParams
object
Obligatoire
Service associé à la couche (OpenLS, WFS, WMTS)
tileMatrixSetLink
string
Optionnel
Nom du TileMatrixSet associé à la couche (seulement
pour les couches WMTS)
projection
String
Optionnel
Identifiant de la projection associée à la couche (défaut
ou celle du TMS pour les couches WMTS).
additionalSRS
array({string})
Optionnel
Tableau contenant les autres SRS associés à la couche
(pour les couches WFS notamment).
featurePrefix
string
Optionnel
Le préfixe dans le nom de la ressource (seulement pour
les couches WFS). Ce paramètre ne provient pas de la
réponse de l'auto-configuration, mais peut être récupéré
à partir du nom de la couche (tout comme le paramètre
typename ci-dessous) : c'est le nom de la ressource,
correspondant à la chaîne de caractère avant les '':'' dans
le nom de la couche (par exemple :
BDCARTO_BDD_GLP_WGS84G_20131216).
typename
string
Optionnel
Le type d'entité, pour les couches WFS seulement. Il
correspond à la chaîne de caractères située après les '':''
dans le nom de la couche (par exemple : 'parcelle').
featureNS
string
Optionnel
Le namespace associé à la ressource. (uniquement pour
les couches WFS).
Ce paramètre ne provient pas non plus de la réponse de
l'auto-configuration, il ne sera donc pas rempli. Il peut
être
récupéré
à
l'aide
d'une
requête
DescribeFeatureType.
geometryName
string
Optionnel
Nom de l'attribut où est stockée la géométrie
(uniquement pour les couches WFS).
Comme featureNS, il ne sera pas rempli à l'aide de la
réponse de l'auto-configuration, mais peut être récupéré
avec un DescribeFeatureType.
metadata
Array({object})
Optionnel
Informations concernant les métadonnées associées à la
couche (la liste des propriétés est détaillée plus loin).
styles
Array({object})
Optionnel
Informations concernant les styles associés à la couche
(normal, bdparcellaire, …).
La liste des propriétés est détaillée plus loin.
legends
Array({object})
Optionnel
Informations concernant les légendes associées à la
originators
Array({object})
Optionnel
Informations concernant les propriétaires des données
(originators). La liste des propriétés est détaillée plus
loin.
thematics
Array({object})
Obligatoire
Informations concernant les thématiques associées à la
formats
Array({object})
Optionnel
Informations concernant les formats des données (la
liste des propriétés est détaillée plus loin).
dimensions
Object
Optionnel
Informations concernant les dimensions associées aux
données (la liste des propriétés est détaillée plus loin).
constraints
Array({object})
Optionnel
Informations concernant des contraintes associées à la
21/94
Propriété
Type
Opt.
Valeur
aggregationOptions
Object
Optionnel
Informations concernant l'agrégation de couches.
Permet de savoir par exemple si la couche est un
agrégat. La liste des propriétés est détaillée plus loin.
Propriétés de l'objet territories :
L'objet TERRITORIES a pour propriétés l'ensemble des identifiants des territoires disponibles, par
exemple 'FXX'. Pour chaque territoire, les propriétés sont détaillées ci-dessous :
Propriété
Type
Opt.
Valeur
isDefault
Boolean
Obligatoire
Vaut 'true' si c'est le territoire à charger par défaut, ou
'false' sinon.
defaultCRS
String
Obligatoire
Identifiant de la projection associée par défaut au
territoire (par exemple 'EPSG:3857').
additionalCRS
Array({string})
Obligatoire
Autres projections associées au territoire, sous forme
d'un tableau contenant les identifiants des projections.
geoBBOX
op,bottom})
l'étendue spatiale du territoire (en coordonnées
géographiques WGS84)
geoCenter
Object({lon,lat})
Obligatoire
Objet contenant la latitude et longitude du centre du
territoire (en coordonnées géographiques WGS84).
defaultOptions
Object
Obligatoire
Les niveaux de zoom utilisés par défaut pour ce
territoire. La liste des propriétés est détaillée plus loin.
defaultLayers
Array({string})
Obligatoire
Tableau contenant les identifiants des couches associées
par défaut à ce territoire (par exemple,
GEOGRAPHICALGRIDSYSTEMS.MAPS$GEOPORT
AIL:OGC:WMTS).
Propriétés de l'objet tileMatrixSets :
L'objet TILEMATRIXSETS a pour propriétés l'ensemble des identifiants des TMS disponibles, par
exemple 'PM'. Pour chaque TMS, les propriétés sont détaillées ci-dessous :
Propriété
Type
Opt.
Valeur
projection
String
Obligatoire
La projection associée (par exemple 'EPSG:3857').
nativeResolutions
Array({float})
Obligatoire
Tableau contenant les résolutions associées aux
différents niveaux de zoom, calculées à partir des
échelles des niveaux de la pyramide (matrixIds).
matrixIds
Array({object})
Obligatoire
Tableau contenant les informations des niveaux de la
pyramide (matrixIDs), sous forme d'objets. La liste des
propriétés de ces objets est détaillée plus loin.
22/94
Propriétés de l'objet services :
L'objet SERVICES a pour propriétés l'ensemble des services disponibles, par exemple
'OGC:WMTS'. Pour chaque service, les propriétés sont détaillées ci-dessous :
Propriété
Type
Opt.
Valeur
title
String
Obligatoire
Titre du service (par exemple 'Point altimetrique')
serverUrl
String
Obligatoire
URL du serveur associé à ce service (par exemple
'http://wxs.ign.fr/geoportail/ols')
version
String
Obligatoire
Version du service (par exemple 2.0.0)
Propriétés de l'objet apiKeys (de l'objet generalOptions) :
L'objet apiKeys a pour propriétés la ou les clés de contrat pour lesquelles la configuration a été
demandée (chaînes de caractères). Pour chaque clé, les propriétés sont détaillées ci-dessous :
Propriété
allowedLayers
Type
Array({string})
Opt.
Valeur
Obligatoire
Liste des identifiants des couches disponibles pour cette
clé de contrat.
Propriétés de l'objet serviceParams (de l'objet Layers) :
Propriété
Type
Opt.
Valeur
type
String
Obligatoire
Type du service (WFS, WMTS, OpenLS)
serviceUrl
Array({string})
Obligatoire
Tableau contenant les URL du service (avec la ou les
clé(s) de contrat associées à la couche)
version
String
Obligatoire
Version du service
Propriétés des objets du tableau metadata (de l'objet Layers) :
Propriété
Type
Opt.
Valeur
format
String
Obligatoire
Format du fichier de métadonnées (généralement
XML).
url
String
Obligatoire
URL du fichier de métadonnées
xlinkType
String
Obligatoire
Type du lien XML, généralement 'simple'.
Propriétés des objets du tableau styles (de l'objet Layers) :
Propriété
Type
Opt.
Valeur
name
String
Obligatoire
Identifiant du
'bdparcellaire').
title
String
Obligatoire
Titre décrivant un peu plus le style.
current
Number
Optionnel
Vaut 1 si le style actuel est sélectionné, 0 sinon.
23/94
style
(par
exemple
'normal'
ou
Propriétés des objets du tableau legends (de l'objet Layers) :
Propriété
Type
Opt.
Valeur
format
String
Obligatoire
Format de la légende.
/!\ Vaut toujours 'format' pour l'instant...
url
String
Obligatoire
URL du fichier de légende
maxScale
Number
Obligatoire
Dénominateur de l'échelle maximum à laquelle la
légende est disponible.
xlinkType
String
Obligatoire
Type du lien XML, généralement 'simple'.
Propriétés des objets du tableau Originators (de l'objet Layers) :
Propriété
Type
Opt.
Valeur
name
String
Obligatoire
Identifiant du propriétaire des données
attribution
String
Obligatoire
Nom complet du propriétaire des données
logo
String
Obligatoire
Url du logo du propriétaire des données
url
String
Obligatoire
URL du propriétaire des données (par exemple,
http://www.ign.fr)
bounds
op,bottom})
Objet contenant les coordonnées des extrémités de la
couverture spatiale des données de ce producteur (en
coordonnées géographiques WGS84) .
minZoomLevel
Number
Obligatoire
Zoom minimum correspondant aux données couvertes
par cet originator.
maxZoomLevel
Number
Obligatoire
Zoom maximum correspondant aux données couvertes
par cet originator.
Propriétés des objets du tableau thematics (de l'objet Layers) :
Propriété
Type
Opt.
Valeur
inspire
String
Optionnel
Vaut 'true' si c'est une thématique Inspire, 'false' si c'est
une thématique autre.
name
String
Obligatoire
Intitulé de la thématique.
Propriétés des objets du tableau formats (de l'objet Layers) :
Propriété
Type
Opt.
Valeur
current
Boolean
Obligatoire
Vaut true si c'est le format actuel sélectionné, false
sinon.
name
String
Obligatoire
Nom du format des données (par exemple, 'image/png').
24/94
Propriétés de l'objet dimensions (de l'objet Layers) :
Propriété
Type
Opt.
Valeur
type
String
Optionnel
Type de visualisation (2D)
visibilityRange
String
Optionnel
Échelle de visualisation
visibilityMode
String
Optionnel
Exemple : 'resolution', 'distance'
noDataValue
String
Optionnel
Exemple : 'FFFFFF'
geometricType
String
Optionnel
Type de géométrie (uniquement pour les couches WFS)
Propriétés des objets du tableau constraints (de l'objet Layers) :
Propriété
Type
Opt.
Valeur
crs
String
Optionnel
Identifiant de la projection associée.
bbox
Object({left,right,t Optionnel
op,bottom})
l'étendue correspondant à la contrainte (en coordonnées
géographiques WGS84)
minZoomLevel
Number
Obligatoire
Niveau de zoom minimum
maxZoomLevel
Number
Obligatoire
Niveau de zoom maximum
temporalExtent
Array({float})
Optionnel
Tableau contenant deux dates sous forme de chaines de
caractères, correspondant aux extrémités de l'étendue
temporelle :
[minT, maxT]
Propriétés de l'objet aggregationOptions (de l'objet Layers) :
Propriété
Type
Opt.
Valeur
isAggregate
Boolean
Obligatoire
Permet de savoir si la couche est un agrégat d'autres
données.
aggregatedLayers
Array({string})
Optionnel
Objet contenant la liste des identifiants des couches
agrégées formant l'agrégat.
Cette liste n'apparaît que lorsque l'utilisateur a demandé
explicitement des informations sur l'agrégat.
Propriétés de l'objet defaultOptions (de l'objet Territories) :
Propriété
Type
Opt.
Valeur
defaultZoomLevel
Number
Obligatoire
Le zoom spécifié par défaut pour ce territoire.
minZoomLevel
Number
Obligatoire
Le zoom minimum spécifié par défaut pour ce territoire.
maxZoomLevel
Number
Obligatoire
Le zoom maximum spécifié par défaut pour ce
25/94
Propriété
Type
Opt.
Valeur
territoire.
Propriétés des objets du tableau matrixIds (de l'objet TileMatrixSets) :
Chaque élément de matrixIds a pour propriétés l'ensemble des identifiants d'un niveau de matrice.
Pour chaque niveau, les propriétés sont détaillées ci-dessous :
Propriété
Type
Opt.
Valeur
matrixId
Number
Obligatoire
Identifiant de la matrice (= niveau de pyramide) : entier
entre 0 et 21.
matrixHeight
Number
Obligatoire
Hauteur de la matrice, en nombre de tuiles
matrixWidth
Number
Obligatoire
Largeur de la matrice, en nombre de tuiles
scaleDenominator
Float
Obligatoire
Dénominateur d'échelle associé à ce niveau (permet de
calculer la résolution associée)
tileHeight
Float
Obligatoire
Hauteur des tuiles, en pixels (généralement 256)
tileWidth
Float
Obligatoire
Largeur des tuiles, en pixels (généralement 256)
topLeftCorner
Array({float})
Obligatoire
Coordonnées d'origine des tuiles (coin « en haut à
gauche »), dans la projection du TileMatrixSet : [x, y].
Quelques remarques :
Plusieurs clés
Si plusieurs clés sont spécifiées, les informations relatives aux deux clés de contrat seront alors
disponibles dans la variable Gp.Config. La clé spécifiée dans l'objet layers permet de savoir à quel
contrat est associé chaque ressource, et donc de bien différencier les droits relatifs à chaque clé
(notamment si on prévoit de gérer l'utilisation de plusieurs clés dans l'API).
Informations des couches agrégées
Si l'identifiant d'une couche agrégée est spécifié, les informations spécifiques à l'agrégation seront
ajoutées dans la variable globale Gp.Config, dans les informations de la couche agrégée (l'agrégat
final des autres couches).
Informations manquantes pour les couches WFS
Les informations retournées par le service, et stockées dans l'objet Gp.Config ne sont pas
suffisantes, notamment pour afficher une couche WFS. En effet, il est nécessaire de connaître des
paramètres concernant le protocole WFS : le namespace de la couche (featureNS) ainsi que le nom
de l'attribut contenant la géométrie (geometryName). Ces deux éléments ne peuvent être récupérés
qu'avec une requête DescribeFeatureType sur la couche que l'on veut récupérer. De même, il est
nécessaire de connaître le featurePrefix ainsi que le typename, qui peuvent être récupérés à partir du
nom de la ressouce.
On peut récupérer les paramètres featurePrefix et typename à partir du nom de la ressource pour les
ajouter
à
la
variable
globale.
Par
exemple
avec
la
ressource
BDCARTO_BDD_GLP_WGS84G_20131216:commune :
•
featurePrefix
: la chaine de caractères avant les « : » dans le nom de la ressource. Par
26/94
exemple, featurePrefix = BDCARTO_BDD_GLP_WGS84G_20131216.
•
typename : la chaine de caractères après les « : » dans le nom de la
ressource. Par exemple, typename = commune.
En revanche, pour les paramètres featureNS et geometryName, on les laissera vide. Lorsqu'on
souhaitera ajouter une couche WFS, on pourra essayer les propositions suivantes :
: uri composée de la manière suivante : http://wxs.ign.fr/datastore/featurePrefix.
Par exemple, http://wxs.ign.fr/datastore/BDCARTO_BDD_GLP_WGS84G_20131216
•
featureNS
•
geometryName = 'the_geom' ou 'geom'
Exemples d'utilisation :
Utilisation de la fonction getConfig()
Exemple 1 : Première opération de l'autoconf avec une clef ; utilisation des différentes fonctions de
rappel.
Gp.services.getConfig({
apiKey: 'CLE_API',
onSuccess: function(config){
console.log("Succès de la lecture de l'auto-configuration");
//affiche le contenu de la variable Geoportal.Config
console.log(config);
},
onFailure: function(error){
console.log("erreur de récupération des paramètres d'autoconfiguration");
console.log("erreur : "+error.errorStatus);
console.log(error.message);
}
}) ;
L'objet config de la fonction onConfLoaded correspond à la variable globale Gp.Config. On peut
alors visualiser notamment les différentes ressources auxquelles on a accès avec sa clé dans l'objet
config.layers.
Exemple 2 : getConfig avec plusieurs clefs.
apiKey: [
'CLE_1',
'CLE_2'
],
console.log(config.generalOptions.apiKeys);
},
}) ;
Pour visualiser rapidement les ressources disponibles pour chacune des clés, on peut visualiser
l'objet Gp.Config.generalOptions.apiKeys, qui liste pour chaque clé les identifiants des couches
disponibles.
Exemple 3 : Utilisation du paramètre layerId (deuxième opération de l'autoconf).
27/94
apiKey: 'CLE_API',
layerID: "GEOGRAPHICALGRIDSYSTEMS.MAPS.3D$GEOPORTAIL:OGC:WMTS@aggregate",
onSuccess(config) {
},
}) ;
On peut alors visualiser le nom des couches composant la couche agrégée dans le tableau :
config.layers["GEOGRAPHICALGRIDSYSTEMS.MAPS.3D$GEOPORTAIL:OGC:WMTS@aggr
egate"].aggregationOptions.aggregatedLayers[].
Exemple 4 : Autoconf chargée localement.
Gp.services.getConfig(
serverUrl: "autoconf.js",
}
) ;
Exemple 5 : Autoconf en GET sans passer par le protocole JSONP. Utilisation d'un proxy.
Gp.services.getConfig(
apiKey: 'CLE_API',
},
protocol:'XHR',
proxyURL: "/proxy/proxy.php",
httpMethod:'GET'
) ;
Le résultat est le même : l'ensemble des informations associées à son contrat sont présentes dans la
variable Gp.Config.
Exemple 6 : Autoconf en POST. Utilisation d'un proxy.
apiKey: 'CLE_API',
},
protocol:'XHR',
proxyURL: "/proxy/proxy.php",
httpMethod:'POST'
}) ;
Exploitation des résultats avec OpenLayers 3
Exemple 1 : Affichage d'une couche Géoportail WMTS avec OpenLayers 3 et les informations
issues de l'autoconfiguration.
var map = null;
28/94
apiKey: 'CLE_API',
// la fin de chargement de l'autoconf declenche l'affichage de la carte
onSuccess: initMap
});
function initMap(config){
var layerID= 'GEOGRAPHICALGRIDSYSTEMS.MAPS$GEOPORTAIL:OGC:WMTS';
var layerConf= Gp.Config.layers[layerID];
var territoryConf= Gp.Config.territories;
var TMSconf= Gp.Config.TileMatrixSets[layerConf.TileMatrixSetLink];
map= new ol.Map({
target: 'viewerDiv',
renderer: "dom",
view: new ol.View({
zoom: 7,
center: [288074.8449901076, 6247982.515792289],
maxZoom: territoryConf.defaultOptions.maxZoomLevel
}),
layers: [
new ol.layer.Tile({
source: new ol.source.WMTS({
url: layerConf.serviceParams.serviceUrl
layer: layerConf.name,
matrixSet: layerConf.TileMatrixSetLink,
format: layerConf.formats[0].name,
projection: layerConf.projection,
tileGrid: new ol.tilegrid.WMTS({
origin: TMSConf.matrixIds[0].topLeftCorner,
resolutions: TMSConf.nativeResolutions,
matrixIds: TMSConf.matrixIds
}),
style: layerConf.styles[0].name
})
})
]
});
}
Exemple 2 : Affichage d'une couche WMS Géoportail avec OpenLayers 3 et les données de
l'autoconfiguration. (GEOGRAPHICALGRIDSYSTEMS.MAPS$GEOPORTAIL:OGC:WMS)
var map = null;
apiKey: 'CLE_API',
// la fin de chargement de l'autoconf déclenche l'affichage de la carte
onSuccess : initMap
});
function initMap(config){
var layerID = 'GEOGRAPHICALGRIDSYSTEMS.MAPS$GEOPORTAIL:OGC:WMS';
var layerConf = Gp.Config.layers[layerID];
var territoryConf = Gp.Config.territories;
map = new ol.Map({
target: 'viewerDiv',
view: new ol.View({
zoom: 7,
center: [288074.8449901076, 6247982.515792289],
maxZoom: territoryConf.defaultOptions.maxZoomLevel
}),
29/94
});
layers: [
new ol.layer.Image({
source: new ol.source.ImageWMS({
url: layerConf.serviceParams.serviceUrl,
params: {'LAYERS': layerConf.name}
})
})
]
}
30/94
Géocodage Direct
Il s'agit de proposer une couche logicielle permettant l'utilisation du service de géocodage du
Géoportail4. Cette couche logicielle devra envoyer une requête correctement construite au serveur
de géocodage selon des paramètres passés par le développeur et, parser la réponse du serveur, pour
présenter au développeur les résultats.
Cas d'utilisation
L'utilisateur est un développeur qui souhaite géocoder un ou plusieurs localisants.
Il peut rechercher l'emplacement d'un toponyme, d'une adresse, d'une parcelle cadastrale et filtrer
cette recherche en fonction d'attributs ou de contraintes géographiques.
Il peut utiliser plusieurs méthodes et protocoles pour faire cette recherche.
La réponse du serveur, après avoir été analysée et structurée, lui sera communiquée pour qu'il puisse
ensuite effectuer le traitement qu'il souhaite.
Mise en oeuvre
L'utilisation se fera par l'appel de la fonction statique :
Gp.services.geocode(geocodeOptions)
Propriété
location
Type
String or
Object
Opt.
obligatoire
Valeur
Nom de l'adresse, du toponyme ou de la parcelle
cadastrale recherchée (ou autre type de localisant).
Sous forme de String, la propriété permet de faire une
recherche déstructurée.
Sous forme d'objet, la propriété permet de structurer la
recherche. Dans ce cas, les propriétés possibles de cet
objet sont décrites ci-après.
filterOptions
Object
optionnel
Les propriétés possibles de cet objet sont décrites ciaprès.
maximumResponses
Number
optionnel
Nombre de réponses maximal que l'on souhaite recevoir.
Pas de valeur par défaut. Si le serveur consulté est celui
du Géoportail, la valeur par défaut sera donc celle du
service : 25.
returnFreeForm
Boolean
optionnel
Indique si l'on souhaite en réponse un localisant
concaténée plutôt que structuré.
service : 'false'.
srs
4
String
optionnel
Système de coordonnées dans lequel les paramètres
géographiques en entrée et la réponse du service sont
exprimés.
Les principes du service de Géocodage sont exposés en Annexes.
31/94
Propriété
Type
Opt.
Valeur
service : 'EPSG:4326'.
Propriétés de l'objet location :
Propriété
[propriétés du
localisant]
Type
String
Valeur
Propriété du localisant recherché sous la forme d'un couple clé/valeur à
définir selon les possibilités du serveur.
Le service de géocodage du Géoportail permet de faire des recherches
structurées avec les propriétés : "number", "street", "postalCode" et
"city",
Propriétés de l'objet filterOptions :
Propriété
bbox
Type
Object
Valeur
Emprise dans laquelle on souhaite effectuer la recherche. Les propriétés
possibles de cet objet sont décrites ci-après.
Pas de valeur par défaut.
type
Array(String)
Type de l'objet recherché.
Le service de géocodage du Géoportail permet de rechercher des
'PostionOfInterest' pour des toponymes, des 'StreetAddress' pour des
adresses postales et/ou des 'CadastralParcel' pour des parcelles
cadastrales. D'autres types pourront être rajoutés selon l'évolution du
service.
Par défaut, type = ['StreetAddress'].
[propriétés du filtre]
String
Critère supplémentaire pour filtrer la recherche sous la forme d'un couple
clé/valeur à définir selon les possibilités du serveur ajouté à la requête.
Le service de géocodage du Géoportail permet de filtrer tous les résultats
avec les propriétés : "municipality", "insee", "department", "accuracy" et
"matchType".
Il permet aussi de filtrer les adresses postales avec les propriétés :
"number", "street", "postalCode","quality", "ID", "ID_TR", et "territory".
Il permet de filtrer les toponymes avec les propriétés : "importance",
"nature", "postalCode" et "territory".
Enfin, il permet de filtrer les parcelles cadastrales avec les propriétés :
"sheet", "section", et "absorbedcity".
Propriétés de l'objet bbox:
Propriété
Type
Opt.
Valeur
left
Float
obligatoire
Abscisse du côté gauche de la BBOX
right
Float
obligatoire
Abscisse du côté droit de la BBOX.
32/94
top
Float
obligatoire
Ordonnée supérieure de la BBOX.
bottom
Float
obligatoire
Ordonnée inférieure de la BBOX.
Paramètres de la fonction onSuccess()
La fonction onSuccess() prend en paramètre un objet ayant les propriétés suivantes:
Propriété
Type
Valeur
geocodedLocations
Array({Objet})
Liste des localisants géolocalisées. Les propriétés possibles de cet
objet sont décrites ci-après.
Propriétés des objets de geocodedLocations
Propriété
Type
Valeur
position
Array({x :Float,
y:Float})
Longitude, latitude du résultat dans le système de coordonnées
demandé.
accuracy
Float
Indicateur de pertinence (proximité phonétique et orthographique)
entre la requête et le résultat. Il est compris entre 0 (pas de
correspondance) et 1 (exactement identique).
commune
String
Ville du résultat.
department
String
Département du résultat.
freeform
String
Nom de l'adresse, du toponyme ou de la parcelle dans le cas où une
forme déstructurée a été demandée.
insee
Number
Code INSEE du résultat.
matchType
String
Indique comment a été fait le géocodage : "street number" (à l'adresse
exacte), "street enhanced" (à l'adresse avec interpolation entre les
bornes de début et de fin du tronçon), "street" (à la rue sans
interpolation), "city" (à la commune).
municipality
String
Municipalité du résultat.
Propriétés spécifiques aux adresses postales
bbox
Array(Object)
id
String
id_tr
String
number
String
postalCode
Number
quality
String
street
String
territoire
String
oEmprise de l'adresse dans le système de coordonnées demandé.
p
oIdentifiant BD ADRESSE dans le cas où le résultat est une adresse.
p
oIdentifiant "Route Adresse" de la voie portant l'adresse dans la base BD
pADRESSE.
oNuméro de l'adresse (avec répétiteur s'il y a lieu) .
p
oCode postal de l'adresse.
p
oIndicateur de qualité du géocodage (pour plus d'infos
phttp://api.ign.fr/tech-docs-js/fr/developpeur/search.html)
oNom de la rue dans laquelle se trouve l'adresse.
p
oCode du territoire français où se situe l'adresse
p
33/94
Propriété
Type
Valeur
Propriétés spécifiques aux toponymes
bbox
Array(Object)
oEmprise du toponyme dans le système de coordonnées demandé.
p
importance
Number
oImportance du toponyme.
p
nature
String
oNature du toponyme.
p
postalCode
Number
oCode postal du toponyme.
p
territoire
String
oCode du territoire français où se situe le toponyme.
p
Propriétés spécifiques aux parcelles cadastrales
absorbedCity
String
oCode commune absorbée de la parcelle : lorsqu'une parcelle est issue
pd'une ancienne commune qui a fusionné avec une autre. Sinon, le code
vaut '000'.
cadastralParcel
String
sheet
String
number
String
section
String
oNom de la parcelle.
p
oFeuille de la parcelle.
p
oNuméro de la parcelle.
p
oSection de la parcelle.
p
Les propriétés listées ci-dessus sont celles fournies par le service de géocodage du Géoportail. Dans
le cas de consultations d'un autre service, d'autres propriétés peuvent être retournées.
Paramètres de la fonction onFailure()
La fonction onFailure() prend en paramètre un objet ayant les propriétés suivantes:
Propriété
Type
Valeur
status
Number
Code HTTP de retour du serveur.
message
String
Message de retour du serveur.
Exemples d'utilisations :
Exemple 1 : recherche des coordonnées d'un localisant sur le serveur de géocodage du Géoportail
Gp.services.geocode({
apiKey:"CLEF_API",
location : "rue pasteur, Saint-Mandé",
onSuccess : function(geocodedLocations){
if(geocodedLocations.legth > 0){
console.log(geocodedLocations[0]) ;
}
},
onFailure : function(response){
alert("Erreur "+ response.status + " : " + response.message)
}
}) ;
Exemple 2 : recherche structurée des coordonnées d'un localisant. Limite aux 5 premiers résultats.
Adresses reçues en texte libre.
34/94
apiKey:"CLEF_API",
location : {
street:"rue pasteur",
city : "Saint-Mandé"
},
maximumResponses : 5,
returnFreeForm : true,
if(geocodedLocations.legth > 0){
alert(geocodedLocations[0].freeForm)
}
},
alert("Erreur "+ response.status + " : " + response.message)
}
}) ;
Exemple 3 : Recherche d'adresses ou toponymes avec un filtre attributaire la limitant au
département des Bouches-du-Rhône.
apiKey:"CLEF_API",
location : "rey arles",
filterOptions : {
type:['StreetAddress','PointOfInterest'],
departement :"13"
},
alert(geocodedLocations.length + " réponses")
}
}) ;
Exemple 4 : Recherche d'une parcelle cadastrale avec un filtre géographique exprimée en Lambert
93 (EPSG:2154).
apiKey:"CLEF_API",
location : "000BO01297",
srs : "EPSG:2154",
filterOptions : {
type:['CadastralParcel'],
bbox :{
left : 735394,
right : 884191,
top : 6326325,
bottom : 6236944
}
},
}
}) ;
Exemple 5 : Interrogation en mode AJAX (protocole XHR) et utilisation d'un proxy.
apiKey:"CLEF_API",
35/94
httpMethod : "GET",
protocol : "XHR",
proxyUrl :"/proxy.php?url="
}
}) ;
Exemple 6 : Envoi d'une requête en POST. Utilisation d'un proxy.
apiKey:"CLEF_API",
httpMethod : "POST",
proxyUrl :"/proxy.php?url="
}
}) ;
Exemple 7 : Utilisation d'une autre URL pour le serveur de Géocodage.
serverUrl : "http://pp-gpp3-wxs-ignfr.aw.atosorigin.com/CLEF_API/geoportail/ols",
}
}) ;
36/94
Geocodage inverse
Il s'agit de proposer une couche logicielle permettant l'utilisation du service de géocodage indirect.
Cette couche logicielle devra envoyer une requête correctement construite au serveur de géocodage
indirect selon des paramètres passés par le développeur et, parser la réponse du serveur, pour
présenter au développeur les résultats.
Cas d'utilisation
Il peut rechercher un toponyme et/ou une adresse à proximité d'une position.
Il peut utiliser plusieurs méthodes et protocoles pour faire cette recherche.
La réponse du serveur, après avoir été analysée et structurée, lui sera communiquée pour qu'il puisse
ensuite effectuer le traitement qu'il souhaite.
Mise en oeuvre
L'utilisation se fera par l'appel de la fonction statique.
Gp.services.reverseGeocode(reverseGeocodeOptions)
Propriété
Type
Opt.
Valeur
position
Object({x:Floa obligatoire
t,y:Float})
Abscisse et ordonnée du point de référence pour le calcul
de proximité exprimées dans le système de référence
spécifié par le srs.
srs
String
Système de coordonnées dans lequel les paramètres
géographiques en entrée sont exprimés. La réponse du
service sera alors aussi exprimée dans ce système de
coordonnées.
optionnel
service : 'EPSG:4326'.
filterOptions
Object
optionnel
returnFreeForm
Boolean
optionnel
Indique si l'on souhaite en réponse un localisant exprimé
en texte libre plutôt que dans une forme structurée.
Pas de valeur par défaut. La valeur par défaut sera donc
celle du service : 'false' pour le Géoportail.
maximumResponses
Number
optionnel
Nombre de réponses maximal que l'on souhaite recevoir.
service : 25.
Propriétés de l'objet filterOptions:
Propriété
bbox
Type
Object
Valeur
Emprise dans laquelle on souhaite effectuer la recherche. Les propriétés
37/94
circle
Object
Cercle dans lequel on souhaite effectuer la recherche. Les propriétés
polygon
Array({x:Float,y:F Polygone dans lequel on souhaite effectuer la recherche. Liste des
loat})
couples x et y pour chaque point constituant le polygone.
type
Array(String)
Le service de géocodage du Géoportail permet de rechercher des
'PostionOfInterest' pour des toponymes, des 'StreetAddress' pour des
adresses postales et/ou des 'CadastralParcel' pour des parcelles
cadastrales. D'autres types pourront être rajoutés selon l'évolution du
service.
Propriétés de l'objet bbox:
Propriété
Type
Opt.
Valeur
left
Float
obligatoire
Abscisse du côté gauche de la BBOX
right
Float
obligatoire
Abscisse du côté droit de la BBOX.
top
Float
obligatoire
Ordonnée supérieure de la BBOX.
bottom
Float
obligatoire
Ordonnée inférieure de la BBOX.
Propriétés de l'objet circle:
Propriété
Type
Opt.
Valeur
x
Float
obligatoire
Abscisse du centre du cercle de recherche.
y
Float
obligatoire
Ordonnée du centre du cercle de recherche.
radius
Float
obligatoire
Rayon du cercle de recherche.
Paramètre de la fonction onSuccess()
La fonction onSuccess() prend en paramètre un objet contenant la réponse du service possédant les
propriétés suivantes:
Propriété
geocodedLocations
Type
Array({Objet})
Valeur
Liste des localisants géolocalisés. Les propriétés possibles de
cet objet sont décrites ci-après.
Propriétés des objets de geocodedLocations
38/94
Propriété
Type
Valeur
position
Object({x:Float,
y:Float})
Abscisse du résultat dans le système de coordonnées demandé.
searchCenterDistance
Float
Distance entre le point de référence et le résultat (dépend du
système de coordonnées).
commune
String
Ville du résultat.
department
String
Département du résultat.
insee
Number
Code INSEE du résultat.
matchType
String
Indique comment a été fait le géocodage : "street number" (à
l'adresse exacte), "street enhanced" (à l'adresse avec interpolation
entre les bornes de début et de fin du tronçon), "street" (à la rue
sans interpolation), "city" (à la commune).
municipality
String
Municipalité du résultat.
Propriétés spécificiques aux adresses postales
bbox
Array(Object)
Emprise de l'adresse dans le système de coordonnées demandé.
number
String
Numéro de l'adresse (avec répétiteur s'il y a lieu).
postalCode
Number
Code postal de l'adresse.
quality
String
Indicateur de qualité du géocodage (pour plus d'infos
http://api.ign.fr/tech-docs-js/fr/developpeur/search.html)
street
String
Nom de la rue dans laquelle se trouve l'adresse.
territoire
String
Code du territoire français où se situe l'adresse.
Propriétés spécifiques aux toponymes
bbox
Array(Object)
Emprise du toponyme dans le système de coordonnées demandé.
importance
Number
Importance du toponyme.
nature
String
Nature du toponyme.
postalCode
Number
Code postal du toponyme.
territoire
String
Code du territoire français où se situe le toponyme.
Propriétés spécifiques aux parcelles cadastrales
absorbedCity
String
Code commune absorbée de la parcelle : lorsqu'une parcelle est
issue d'une ancienne commune qui a fusionné avec une autre.
Sinon, le code vaut '000'.
cadastralParcel
String
Nom de la parcelle.
district
String
Arrondissement de la parcelle.
sheet
String
Feuille de la parcelle.
39/94
Propriété
Type
Valeur
number
String
Numéro de la parcelle retournée.
section
String
Section de la parcelle.
Les propriétés listées ci-dessus sont celles fournies actuellement par le service de géocodage du
Géoportail.
Propriété
Type
Opt.
Valeur
status
Number
obligatoire
message
String
obligatoire
Exemple 1 : Recherche d'adresses proches d'un point.
Gp.services.reverseGeocode({
apiKey:"CLEF_API",
position : {
x : 43,6779842,
y : 4,621130
},
console.log(geocodedLocations)
},
alert("Erreur "response.status + " : " + response.message)
}
})
Exemple 2 : Recherche d'adresses proches d'un point. Limitation aux 5 premiers résultats. Adresses
exprimées en texte libre.
Gp.services.reverseGeocode ({
apiKey:"CLEF_API",
position : {
x : 43,6779842,
y : 4,621130
},
returnFreeForm : true,
}
})
Exemple 3 : Recherche d'adresses ou toponymes proches d'un point.
apiKey:"CLEF_API",
position : {
x : 43,6779842,
40/94
y : 4,621130
},
filterOptions : {
type:['StreetAddress','PointOfInterest']
}
}
}) ;
Exemple 4 : Recherche de parcelles proches d'un point dans une zone de recherche rectangulaire
exprimée en Lambert 93.
apiKey:"CLEF_API",
position : {
x : 755394,
y : 6296944
}
srs : "EPSG:2154",
filterOptions : {
type:['CadastralParcel'],
bbox:{
left : 735394,
right : 884191,
top : 6326325,
down : 6236944
}
},
alert(geocodedLocations.length + " réponses") ;
}
})
41/94
Autocomplétion
Il s'agit de proposer une couche logicielle permettant l'utilisation du service d'autocomplétion 5.
Cette couche logicielle devra envoyer une requête correctement construite au serveur
d'autocomplétion selon des paramètres passés par le développeur et, parser la réponse du serveur,
pour présenter au développeur les résultats.
Cas d'utilisation
Le cas d'utilisation classique est le champ de saisie texte d'un moteur de recherche dans une
application dont on veut qu'il propose des suggestions d'adresses ou de toponymes au fur et à
mesure de la saisie. Les suggestions peuvent alors être ré-exploitées, soit pour récupérer les
coordonnées qui y sont associées, soit comme critère de recherche pour le service de Géocodage du
Géoportail (recherche plus pertinente et informations attributaires plus riches).
Mise en oeuvre
L'utilisation se fera par l'appel de la fonction statique.
Gp.services.autocomplete(autocompleteOptions)
Propriétés de l'objet autocompletOptions :
Propriété
Type
Opt.
Valeur
text
String
obligatoire
La chaîne de caractère à compléter. Cette chaîne n'est
pas "URL encodée". C'est l'API qui s'occupe de
l'encoder pour l'inclure dans la requête.
filterOptions
Object
optionnel
maximumResponses
Number
optionnel
Nombre de réponses maximales que l'on souhaite
recevoir.
Pas de valeur par défaut. La valeur par défaut sera
donc celle du service : 10.
Propriétés de l'objet filterOptions :
Propriété
type
Type
Array(String)
Valeur
Le service d'autocomplétion du Géoportail permet de rechercher des
toponymes 'PostionOfInterest' et/ou des adresses postales
'StreetAddress'. D'autres types pourront être rajoutés selon l'évolution du
service.
territory
Array(String)
Limitation de la zone de recherche de localisants.
Le service d'autocomplétion du Géoportail permet de limiter la recherche
à la métropole et la Corse 'METROPOLE', aux DOMS TOMS
5
Le fonctionnement du service est précisé en annexes.
42/94
'DOMSTOMS', à une liste de codes de départements ou codes INSEE de
communes.
Pas de valeur par défaut. La valeur par défaut est donc celle du service.
Le service d'autocomplétion du Géoportail renvoie toutes les
informations quand aucun territoire n'est spécifié.
Paramètres de la fonction onSuccess(autocompleteResponse)
La fonction onSuccess() prend en paramètre un objet ayant les propriétés suivantes:
Propriété
Type
Valeur
status
String
suggestedLocations
Array({Objet})
Liste des localisants proposés par le service. Les propriétés possibles de
cet objet sont décrites ci-après.
Propriétés de l'objet suggestedLocations:
Propriété
Type
Valeur
position
Object({x :Flo Longitude et latitude du résultat dans le système de coordonnées demandé.
at, y :Float})
commune
String
Ville du résultat.
fullText
String
Nom complet de l'adresse, du toponyme.
poi
String
Propre aux toponymes.
Nom du lieu.
postalCode
Number
Propre aux adresses postales et toponymes.
Code postal de l'adresse ou du toponyme géolocalisée.
classification
Integer
Valeur fonction de la nature du localisant. Pour les communes, ce chiffre
varie de 1 (capitale) à 6 (commune). Pour les autres toponyme, il est égal à
8.
kind
String
Propre aux toponymes.
Type de toponymes ( par exemple "préfecture", monument, "commune"... ).
street
String
Propre aux adresses postales.
Nom de la rue.
Propriété
Type
Valeur
status
Number
message
String
43/94
Exemples d'utilisations
Exemple 1 : Demande de suggestions d'adresses commencant par "rue pasteur, Sai" .
Gp.services.autocomplete({
apiKey:"CLEF_API",
text : "rue pasteur, Sai",
onSuccess : function(autocompleteResponse){
console.log(autocompleteResponse)
},
onFailure : function(autocompleteResponse){
alert("Erreur "autocompleteResponse.status + " : " +
autocompleteResponse.message)
}
}) ;
Exemple 2 : Demande de suggestions d'adresses ou de toponymes commençant par "rue pasteur,
Sai". Restriction de la recherche sur le département 94. Limitation du nombre de réponses.
Gp.services.autocomplete ({
apiKey:"CLEF_API",
text : "rue pasteur, Sai",
filterOptions:{
type:['StreetAddress','PositionOfInterest'],
territory :["94"]
},
onSuccess : function(autocompleteResponse){
alert(autocompleteResponse.suggestedLocations.length + " réponses")
}
}) ;
Exemple 3 : Utilisation du service de géocodage sur une autre URL.
text : "rue pasteur, Saint-Man",
serverUrl : "http://pp-gpp3-wxs-i-ignfr.aw.atosorigin.com/CLEF_API/geoportail/ols/apis/completion"
onSuccess : function(geocodedResponse){
alert(geocodedResponse.suggestedLocations.length + " réponses")
}
}) ;
44/94
Calcul d'itinéraires
Il s'agit de proposer une couche logicielle permettant d'utiliser le service de calcul d'itinéraires du
Géoportail6. Elle permet à l'utilisateur de passer ses paramètres en entrée du service et d'en
récupérer l'itinéraire et les instructions dans une structure JSON en retour.
Cas d'utilisation
L'utilisateur est un développeur qui souhaite mettre en œuvre un formulaire permettant de saisir des
points de départ et d'arrivée et de déterminer un itinéraire à partir du service de calcul d'itinéraires
du Géoportail. Il souhaite pouvoir afficher la géométrie de l'itinéraire avec une API cartographique
du marché.
Mise en œuvre
L'invocation du service se fait via l'appel d'une fonction statique
Gp.services.route(routeOptions)
Paramètre
Type
Opt.
Valeur
routePreference
String
Optionnel
Mode de calcul à utiliser :
* le plus rapide « fastest »
* le plus court « shortest »
* piéton « pedestrian »
Par défaut : « fastest ».
startPoint
Object
Obligatoire
Point de départ du calcul. Coordonnées exprimées en
longitudes, latitudes (EPSG:4326) :{x:float, y:float}
endPoint
Object
Obligatoire
Point d'arrivé du calcul. Coordonnées exprimées en
viaPoints
Array(Object)
Optionnel
Liste de point intermédaires que l'itinéraire doit emprunter
dans l'ordre du tableau. Coordonnées exprimées en
vehicle
String
Optionnel
Type de véhicule utilisé « voiture ».
Détermine le profil de vitesses utilisé pour le calcul ainsi
que les tronçons autorisés ou non.
Par défaut, c'est la valeur voiture qui sera utilisée.
Si routePreference vaut « pedestrian », alors le paramètre
vehicle est ignoré.
exclusions
Array(String)
Optionnel
Critères d'exclusions à appliquer pour le calcul.
On précise ici le type de tronçons que l'on ne veut pas que
l'itinéraire emprunte (valeurs possibles : « toll » (éviter les
péages), « bridge », « tunnel »).
provideGeometry
Booléen
Optionnel
Indique si la géométrie de l'itinéraire doit être reprise
morceau par morceau dans les instructions.
Par défaut : false.
provideBbox
Booléen
Optionnel
Indique si les instructions doivent être localisées par une
bbox dans la réponse.
Par défaut : true.
6
Une description du service est fournie en annexes.
45/94
Paramètre
Type
Opt.
Valeur
distanceUnit
String
Optionnel
Unité dans laquelle les distances seront exprimées dans la
réponse (« m » ou « km »).
Par défaut : « km ».
Paramètres de la fonction onSuccess :
La fonction onSuccess prend un objet JSON en entrée, ayant les propriétés suivantes :
Propriété
Type
Valeur
totalTime
float
Durée totale de l'itinéraire (en secondes).
totalDistance
float
Longueur totale de l'itinéraire (en « m » ou « km » selon le
paramètre distanceUnit de la requête).
bbox
bbox
Emprise (rectangle englobant) de l'itinéraire.
routeGeometry
geoJSON
Géométrie de l'itinéraire.
routeInstructions
Array(Object)
Liste des instructions le long de l'itinéraire. Les propriétés d'un objet
d'instructions esont décrites dans le tableau suivant.
Propriétés des instructions :
Propriété
Type
Valeur
duration
Float
Durée (en secondes) de l'instruction
distance
Float
Longueur (en « m » ou « km » selon le paramètre distanceUnit de la
requête)
code
String
Code de l'instuction :
- F : tout droit
- B : demi-tour
- L : tourner à gauche
- R : tourner à droite
- BL : tourner très à gauche
- BR : tourner très à droite
- FL : tourner légèrement à gauche
- FR : tourner légèrement à droite
- round_about_entry : entrée rond-point
- round_about_exit : sortie rond-point :
instruction
String
Texte de l'instruction (traduction du code + nom de la rue
concernée)
bbox
bbox
Emprise (rectangle englobant) de l'instruction.
La présence de cette propriété est déterminée par le paramètre
provideBbox de la requête.
geometry
geoJSON
Géometrie de l'instruction.
La présence de cette propriété est déterminée par le paramètre
provideGeometry de la requête.
Exemple 1 : Calcul d'itinéraire entre deux points donnés et affichage avec OpenLayers 3.
Gp.services.route({
apiKey :'CLEF_API',
startPoint : {
x : 2.25,
y : 45.12
46/94
},
endPoint : {
x : 3.25,
y : 48.12
},
onSuccess : function(route) {
// cf. http://openlayers.org/en/master/examples/geojson.html
var vectorSource = new ol.source.Vector({
features: (new ol.format.GeoJSON()).readFeatures(route.geometry)
});
var vectorLayer = new ol.layer.Vector({
source: vectorSource
});
// l'objet map est un objet ol.Map precedemment cree.
map.addLayer(vectorLayer) ;
}
}) ;
47/94
Calcul d'isochrones / isodistances
Il s'agit de proposer une couche logicielle permettant d'utiliser le service de calcul d'isochrones /
isodistances du Géoportail7. Elle permet à l'utilisateur de passer ses paramètres en entrée du service
et d'en récupérer la géométrie de la courbe calculée et ses caractéristiques dans une structure JSON
en retour.
Cas d'utilisation
L'utilisateur est un développeur qui souhaite mettre en œuvre un formulaire permettant de saisir un
point de départ des paramètres afin de déterminer une courbe ischrone ou isodistance à partir du
service de calcul d'itinéraires du Géoportail. Il souhaite afficher cette courbe avec une API
cartographique du marché.
Mise en œuvre
L'invocation du service se fait via l'appel d'une fonction statique :
Gp.service.processIsoCurve(isoCurveOptions)
Paramètre
Type
Opt.
Valeur
position
Object
Obligatoire
Coordonnées du point de départ (ou d'arrivée) du calcul de
courbe.
Les coordonnées son exprimée sous la forme d'un objet :
{ x:float, y:float}.
Le système de coordonnées est spécifié à l'aide du
paramètre « srs ».
srs
String
Optionnel
Système de coordonnées dans lequel les coordonnées du
point « location » sont exprimées et dans lequel la
géométrie de la courbe résultante sera exprimée.
Par défaut, le système de coordonnées utilisé sera
« EPSG:4326 ».
graph
String
Optionnel
Nom du graphe à utiliser pour le calcul (« pieton » ou
« routier »).
La valeur par défaut est : «routier»
vehicle
String
Optionnel
Profil de véhicule à utiliser pour le calcul.
Pour l'instant, un seul seul type de véhicule est proposé par
le service du Géoportail : « voiture ».
Si graph vaut « pieton » alors le paramètre vehicle est
ignoré.
exclusions
Array(String)
Optionnel
Critères d'exclusions à appliquer pour le calcul.
On précise ici le type de tronçons que l'on ne veut pas que
le calcul utilise (« Toll », « Bridge » ou « Tunnel »).
time
Float
Conditionnel
Durée maximum (exprimée en secondes) à utiliser pour le
calcul de la courbe à partir du ou j'usqu'au point
« location ».
L'utilisation de ce paramètre entraine un calcul d'isochrone.
S'il n'est pas spécifié alors le paramètre distance doit être
renseigné pour déclencher un calcul d'isodistance.
Si les deux paramètres sont renseignés, le paramètre
7
48/94
Paramètre
Type
Opt.
Valeur
distance sera ignoré.
distance
Float
Conditionnel
Distance maximum (exprimée en metres) à utiliser pour le
calcul de la courbe à partir du ou j'usqu'au point
« location ».
L'utilisation de ce paramètre entraine un calcul
d'isodistance.
S'il n'est pas spécifié alors le paramètre time doit être
renseigné pour déclencher un calcul d'isochrone.
Si les deux paramètres sont renseignés, le paramètre
distance sera ignoré.
reverse
Boolean
Optionnel
Indique si le point spécifié via le paramètre « location » doit
être utilisé comme point d'arrivée (« true ») au lieu de point
de départ du calcul (« false »).
Par défaut, la valeur « false » est appliquée.
smoothing
Boolean
Optionnel
Indique si la géométrie résultante doit être lissée (« true »)
pour ne pas avoir d'effet d'escalier.
holes
Boolean
Optionnel
Indique si la géométrie résultante (surface) doit être
retournée avec des trous (« true »).
La fonction onSuccess prend un objet JSON en entrée, ayant les propriétés suivantes :
Propriété
Type
Valeur
message
String
Message éventuel accompagnant la réponse du service
status
String
Status de la réponse du service (« OK »)
id
String
Identifiant de la requête à partir de laquelle la réponse a été calculée
location
Object
Coordonnées du point de départ ou d'arrivée ({x:float, y:float})
exprimées dans le système de coordonnées spécifié via la propriété
« srs ».
srs
String
Système de coordonnées dans lequel les coordonnées de la réponse
sont exprimées.
time
Float
Durée utilisée pour le calcul dans le cas d'une isochrone
distance
Float
Distance utilisée pour le calcul dans le cas d'une isodistance
geometry
geoJSON
Géométrie de la courbe calculée.
Exemple 1 : Calcul d'isochrone à partir d'un point donné et affichage avec OpenLayers 3.
Gp.services.processIsoCurve({
apiKey :'CLEF_API',
position : {
x : 2.25,
y : 45.12
},
time : 1000,
onSuccess : function(isoCurve) {
// cf. http://openlayers.org/en/master/examples/geojson.html
var vectorSource = new ol.source.Vector({
49/94
}
features: (new ol.format.GeoJSON()).readFeatures(isoCurve.geometry)
});
var vectorLayer = new ol.layer.Vector({
source: vectorSource
});
// l'objet map est un objet ol.Map precedemment cree.
map.addLayer(vectorLayer) ;
}) ;
50/94
Services d'altimétrie
Il s'agit de proposer une couche logicielle permettant d'utiliser le service d'altimétrie du Géoportail 8.
Elle permettra à l'utilisateur de choisir le mode d'interrogation du service (API REST ou norme
WPS), le protocole utilisé (XHR ou JSONP), la méthode HTTP – lorsque c'est possible- (GET ou
POST), ou encore le format de sortie. Par défaut, on propose d'utiliser l'API REST, via le protocole
JSONP.
Cas d'utilisation
L'utilisateur est un développeur web qui souhaite intégrer une fonctionnalité de calcul d'altitude
dans son application. Par exemple, il souhaite pouvoir récupérer l'altitude de points saisis une carte
intéractive par un internaute, ou encore proposer un profil altimétrique calculé à partir d'un
échantillonage déterminé par ces points. Il fournit comme paramètres les coordonnées des points
dont il souhaite connaître l'altitude, et éventuellement des paramètres concernant la méthode utilisée
pour interroger le service.
Mise en œuvre
L'utilisation se fera par l'appel d'une seule fonction statique :
Gp.services.getAltitude(altitudeOptions)
On propose une seule fonction, qui gère les deux fonctionnalités du service (calcul d'altitudes
simples : Elevation, ou avec échantillonnage : ElevationLine). La présence d'un paramètre
« sampling », indiquant un pas d'échantillonnage ainsi que la présence de deux points minimum
dans la requête, déclenchera la demande de calcul avec échantillonnage au service.
Description :
Paramètres de l'objet altitudeOptions en entrée de la fonction getAltitude :
Paramètre
Type
Opt.
Valeur
outputFormat
string
Conditionnel
Le format de la réponse du service alti : 'xml' ou 'json'.
Ce paramètre déterminera l'extension '.xml' ou '.json' du
service dans le cas de l'API REST, ou la valeur du
paramètre 'format' dans le cas de la norme WPS.
Nécessaire si serverUrl est renseigné, et qu'on souhaite
passer par l'API REST, pour connaître le format dans lequel
sera fournie la réponse (pour son traitement). Non
nécessaire pour la norme WPS.
Par défaut, ce paramètre vaut 'json'.
positions
Array({x,y})
Obligatoire
Tableau contenant les coordonnées des points (CRS:84)
dont on veut connaître les altitudes (ou à partir desquelles
on va calculer le profil).
Minimum 2 éléments si on souhaite calculer un profil
altimétrique (ElevationLine).
Maximum 50 éléments.
sampling
Integer
Optionnel
Nombre de points à utiliser pour déterminer le tracé d'un
8
51/94
Paramètre
Type
Opt.
Valeur
profil altimétrique, compris entre 2 et 5000.
A spécifier lorsqu'on souhaite accéder à cette fonctionnalité.
Dans ce cas, les points fournis en entrée (au minimum de
deux) servent à déterminer l'axe planimétrique le long
duquel le profil doit être calculé.
Si le paramètre sampling n'est pas spécifié ou moins de
deux points sont fournis, c'est le service Elevation qui sera
interrogé (altitudes simples calculées pour les points
fournis).
Une valeur de sampling strictement inférieure à 2
déclenchera un échantillonnage avec la valeur par défaut du
service (3 points).
api
string
Optionnel
Manière d'accéder au service : 'REST' (via l'API REST) ou
'WPS' (via la norme WPS).
Par défaut, on utilise l'API REST.
zonly
boolean
Optionnel
Permet de ne récupérer que les altitudes en sortie s'il vaut
'true'.
Vaut 'false' par défaut.
La fonction prend en paramètres un tableau contenant les informations des différents points
(coordonnées, altitude, précision) fournis ou échantillonnés. Ce tableau est le même quel que soit le
format de réponse du service spécifié.
Paramètre
Type
Valeur
elevations
array({object})
Objet contenant les informations (lon, lat, z et acc) des points
fournis, dans l'ordre dans lequel ils ont été fournis, et éventuellement
des points échantillonnés.
Propriétés du tableau elevations :
Chaque attribut du tableau elevations est un objet dont les propriétés sont les suivantes :
Paramètre
Type
Valeur
lon
float
Longitude du point fourni (si zonly n'est pas spécifié).
lat
float
Latitude du point fourni (idem)
z
float
Altitude déterminée du point fourni
acc
float
Précision de la valeur au point considéré (si zonly n'est pas spécifié)..
La fonction onFailure prend en paramètre un objet failureData avec les propriétés suivantes :
Paramètre
Type
Valeur
status
number
Code HTTP de retour du serveur, ou -1 si on est en timeout.
(S'il vaut 200, c'est que l'erreur provient de la lecture des paramètres de la
réponse.)
message
string
Message d'erreur. Il peut s'agir de celui renvoyé par le service (not found, clé
invalide, missing parameter), ou d'un message renvoyé par l'API, selon
52/94
Paramètre
Type
Valeur
l'erreur (timeout, exception, structure non reconnue).
Exemple 1 : Récupération de l'altitude d'un point à partir de ses coordonnées, et utilisation des
fonctions de rappel.
Gp.services.getAltitude({
apiKey: 'CLE_API',
positions:[
{x:0.2367,y:48.0551}
],
onSuccess: function(elevations){
// affiche les informations du point fourni
console.log(elevations[0]);
},
onFailure: function(erro){
}
}) ;
Exemple 2 : Récupération des altitudes seulement d'une série de points.
apiKey: 'CLE_API',
positions:[
{x:0.2367,y:48.0551}, {x:1.2099,y:47.3354},
{x:2.157,y:46.607}, {x:3.3003,y:45.2644}, {x:4.3907,y:43.91}
],
zonly:true,
console.log(elevations);
}
}) ;
Exemple 3 : Récupération d'un profil altimétrique de 20 points, à partir de 5 points en entrée.
apiKey: 'CLE_API',
positions:[
{x:0.2367,y:48.0551}, {x:1.2099,y:47.3354},
{x:2.157,y:46.607}, {x:3.3003,y:45.2644}, {x:4.3907,y:43.91}
],
sampling:20,
// informations des points fournis ET échantillonnés
}
}) ;
Exemple 4 : Accès au service en POST, via la norme WPS, et spécification d'un proxy.
apiKey: 'CLE_API',
positions:[
53/94
{x:0.2367,y:48.0551}, {x:1.2099,y:47.3354},
{x:2.157,y:46.607}, {x:3.3003,y:45.2644}, {x:4.3907,y:43.91},
(...)
}) ;
],
api:'WPS',
httpMethod: 'POST',
proxyURL: '/proxy/proxy.php?url=',
}
Exemple 5 : Utilisation d'une autre URL de serveur, en WPS
serverUrl:'http://wxs.ign.fr/CLE_ALTI/alti/wps?service=WPS&version=1.0.0',
positions:[
{x:0.2367,y:48.0551}
],
api:'WPS',
}
}) ;
Exemple 6 : Utilisation d'une autre URL de serveur, en REST
serverUrl: 'http://wxs.ign.fr/CLE_API/alti/rest/Elevation.xml',
outputFormat:'xml',
positions:[
{x:0.2367,y:48.0551}
],
api:'REST',
}
}) ;
54/94
Service WCTS : connaître le domaine de validité d'un Système de coordonnées.
Il s'agit de proposer une couche logicielle permettant d'utiliser l'opération getValidityArea du
service de transformations de coordonnées du Géoportail9.
Cas d'utilisation
L'utilisateur invoque le service WCTS pour connaître le domaine de validité d'un système de
coordonnées dont il fournit l'identifiant. Il reçoit en retour les coordonnées de l'emprise
géographique (rectangle englobant) du système de coordonnées.
Mise en œuvre
Gp.services.getSrsValidityArea(options)
Description :
Paramètres de l'objet options en entrée de la fonction srsValidityArea :
Paramètre
Type
Opt.
Valeur
identifier
String
Obligatoire
identifiant du système de coordonnées, compréhensible par
le service (la liste des identifiants supportés est disponible à
l'aide de l'opération DescribeProcess sur le processus
GetValidityArea
(http://wxs.ign.fr/CLEF/geoportail/wps?
Service=WPS&Request=DescribeProcess&Version=1.0.0&
Identifier=GetValidityArea )
La fonction onSuccess prend en paramètre un objet ayant les propriétés suivantes :
Paramètre
Type
Valeur
bbox
array(Float)
Objet contenant les coordonnées, exprimées longitudes, latitudes
(EPSG:4326) du rectangle englobant décrivant la zone de validité,
dans l'ordre suivant : [lonMin, latMin, lonMax, latMax].
La fonction onFailure prend en paramètre un objet error avec les propriétés suivantes :
Paramètre
Type
Valeur
status
number
(S'il vaut 200, c'est que l'erreur provient de la lecture des paramètres de la
réponse.)
message
string
9
55/94
Exemple 1 : Récupération du domaine de validité d'un SRS, et utilisation des fonctions de rappel.
Gp.services.getSrsValidityArea ({
apiKey: 'CLE_API',
identifier:'IGNF:LAMB93',
onSuccess: function(validityArea){
// bbox du domaine de validité
console.log(validityArea.bbox);
},
}
}) ;
56/94
Service WCTS : transformer des coordonnées
Il s'agit de proposer une couche logicielle permettant d'utiliser l'opération « TransformCoordinates »
du service de transformations de coordonnées du Géoportail10.
Cas d'utilisation
L'utilisateur invoque le service WCTS pour transformer les coordonnées d'une liste de points d'un
système de coordonnées vers un autre dont il fournit les identifiants. Il reçoit en retour la liste des
points avec leurs coordonnées exprimées dans le système de coordonnées cible.
Mise en œuvre
Gp.services.transformCoordinates(options)
Description :
Paramètres de l'objet options en entrée de la fonction transformCoordinates :
Paramètre
Type
Opt.
Valeur
sourceCRS
String
Optionnel
Identifiant du système de coordonnées, compréhensible par
TransformCoordinates
Identifier=TransformCoordinates )
Par défaut la valeur utilisée est : IGNF:LAMB93
targetCRS
String
Optionnel
Identifiant du système de coordonnées, compréhensible par
TransformCoordinates.
Identifier=TransformCoordinates )
Par défaut la valeur utilisée est : IGNF:LAMB93
points
Array({x :Float, Obligatoire
y:Float})
Liste des points dont on veut transformer les coordonnées.
Chaque point est exprimé via un objet javascript ayant la
structure suivante : {x : Float, y : Float}.
nadgridMode
String
Comportement face aux grilles de changement de système
de référence. Le mode « strict » applique la grille seulement
entre les 2 datums correspondants à cette grille
(comportement Circé : http://geodesie.ign.fr). Le mode
« relax » applique toujours la grille dès qu’un des datums
demandé correspond à cette grille (comportement Proj4).
Par défaut, la valeur « relax » est appliquée.
Optionnel
La fonction onSuccess prend en paramètre un objet ayant les propriétés suivantes :
10 Une description du service est fournie en annexes.
57/94
Paramètre
Type
Valeur
points
Array({x:Float, y:Float}) Liste des points transformés.
Elle est ordonnée dans le même ordre que la liste passée en
paramètres
La fonction onFailure prend en paramètre un objet error avec les propriétés suivantes :
Paramètre
Type
Valeur
status
number
message
string
Exemple 1 : Transformation des coordonnées d'une liste de points. Utilisation des fonctions de
rappel.
Gp.services.transformCoordinates ({
apiKey: 'CLE_API',
sourceCRS:'EPSG:4326',
targetCRS:'IGNF:LAMB93',
points: [{x:2.0, y:45},{x:3.0, y:45}],
onSuccess: function(results){
// bbox du domaine de validité
console.log(results.points);
},
}
}) ;
58/94
Gp.formats : Gestion des formats relatifs aux services
Les services de la plateforme Géoportail exposent selon les cas plusieurs interfaces pour exprimer
les requêtes et formuler les réponses.
L'API Géoportail Services propose une interface permettant de faire abstraction de ces protocoles
de dialogue. Elle utilisera et exposera cependant des classes utilitaires permettant de gérer les
différents formalismes, essentiellement lorsqu'il sagit d'exprimer des requêtes ou de traiter des
réponses en XML (éventuellement encapsulé en JSON pour ces dernières).
On proposera ainsi des classes dédiées au traitement :
* du formalisme WPS pour les services d'altimétrie et WCTS ;
* du standard OpenLS pour les services de Géocodage et de calcul d'itinéraires ;
* de la syntaxe de réponse du service d'autoconfiguration ;
* du formalisme XML propriétaire du service d'altimétrie du Géoportail.
* des formalismes WKT et GML pour l'expression des géométries exposées par les différents
services (Géocodage, Itinéraire, Isochrones / Isodistances, … ) ;
* d'autres formats pourront être pris en charge en fonction de l'évolution des interfaces des services
de la plateforme.
Chacune de ces classes exposera :
* des fonctions d'écriture au format XML, dans la syntaxe attendue par le service ;
* des fonctions d'analyse des syntaxes XML relatives aux services ;
* des fonctions d'écriture des réponses dans le format attendu en paramètre des fonctions de rappel
onResponse associées à l'invocation des services par l'API.
Packaging
L'API Géoportail Services sera disponible sous la forme d'un fichier Javascript permettant d'accéder
à toutes les fonctionnalités décrites dans ce document.
59/94
Annexes
Principe du filtre JSONP
Sur la plateforme Géoportail, le protocole JSONP est opérationnel pour des requêtes émises en
HTTP GET. Il est activé lorsque le paramètre « callback » est ajouté à l'URL de la requête. Ce
paramètre prend pour valeur le nom d'une fonction prenant en paramètre un objet JSON contenant
la réponse du service. L'utilisation du paramètre callback=nomDeFonction a pour conséquence
l'intégration de la réponse du service comme paramètre de l'appel javascript de la fonction
nomDeFonction :
nomDeFonction(réponse du service)
Pour des services répondant uniquement en XML, l'utilisation du paramètre output=json est
nécessaire et a pour conséquence l'encapsulation de la réponse du service dans une coquille JSON :
{
http : {
status : code http de la réponse du service (200, 403, ...)
error :
},
xml : 'réponse brute du service'
}
Ce paramètre est inutile pour les services, comme l'autocomplétion, répondant nativement en json.
L'utilisation du paramètre callback=nomDeFonction a alors pour conséquence l'intégration de la
réponse du service encapsulée en JSON comme paramètre de l'appel javascript de la fonction
nomDeFonction :
nomDeFonction({http : {status:200, error:null},xml :'réponse du service'})
De ce fait, l'appel du service pourra se faire via l'intégration d'une balise <script> dans la page html,
entrainant alors l'appel de la fonction qui va en traiter le résultat.
< !-- script de traitement des résultats -->
<script type='text/javascript'>
function nomDeFonction(objResultat) {
// traitement du resultat du service transmis dans l'objet objResultat.xml
...
}
< !-- appel du service -->
</script>
<script type='text/javascript' src='http://wxs.ign.fr/CLEF/service?
parametres=valeurs&output=JSON&callback=nomDeFonction/>
Un script javascript peut donc ainsi envoyer des requêtes vers les services de la plateforme
Géoportail en intégrant dynamiquement cette dernière balise <script> dans la page tout en ayant
pris soin d'implémenter la fonction de callback de traitement du résultat. Les appels du service ne
seront alors pas bloqués par les contraintes de sécurité « cross-domain » des navigateurs.
60/94
Principe de l'auto-configuration
L'infrastructure du Géoportail propose un service, dit d'auto-configuration qui, pour une ou
plusieurs clés données, retourne des informations telles que :
• les paramètres permettant de configurer une visualisation web par défaut (taille, territoire,
couches à afficher) ;
• les paramètres techniques (configuration des services WMTS : TileMatrixSets, listes des
résolutions, configuration des territoires : emprise, centre de visualisation, ...) ;
la liste des ressources (couches) disponibles et les informations permettant d'y accéder (url,
emprises, échelles d'affichage, ...).
Le service d’auto-configuration possède deux opérations.
La première opération permet de récupérer un ensemble d’informations relatives à des couches
agrégées et non-agrégées ainsi que des informations supplémentaires permettant d’initialiser la
visualisation.
La seconde opération permet, à partir de l’id d’une couche, d’obtenir des informations plus
détaillées pour les couches agrégées. Il est ainsi possible de récupérer le détail de l’agrégat, les
intervalles temporels des données, etc. Pour chaque ressource retournée par le service, un champ
"more" permet de savoir s’il est possible de demander la seconde opération afin d’avoir des détails
supplémentaires sur la ressource.
Accès au service :
1ère opération :
On accède au service via une URL du type :
http://wxs.ign.fr/CLE/autoconf/?keys=CLE,CLE2,…
Les clés sont passées en paramètres afin de ne récupérer que les ressources sur lesquelles elles ont
les droits. Si aucune clé n'est spécifiée, la description de toutes les ressources exposées par
l'infrastructure Géoportail est retournée.
Paramètre
valeur
CLE
La clé de contrat API principale détenue par l’utilisateur (optionnel)
?keys=CLE2,...
La liste des clés secondaires, séparées par des virgules (optionnel)
Le service est requêtable en GET et le format de sortie est paramétrable à l’aide du paramètre
optionnel output qui peut prendre les valeurs suivantes : xml (valeur par défaut) ou json.
Par exemple :
http://wxs.ign.fr/CLE/autoconf/?output=json&callback=nomDeFonction
Remarque : l'utilisation du paramètre callback=nomDeFonction a pour conséquence l'intégration
de la réponse du service encapsulée en JSON comme paramètre de l'appel javascript de la fonction
nomDeFonction :
nomDeFonction({http : {status:200, error:null},xml :'réponse du service'})
61/94
2ème opération :
La seconde opération du service prend les mêmes paramètres si on ne spécifie pas de clé de contrat,
mais en ajoutant l'identifiant de la couche (unique) dont on souhaite connaître les informations
supplémentaires à la fin de l'url, de la façon suivante :
http://wxs.ign.fr/autoconf/id/LAYER_ID
Pour récupérer les informations associées à une clé de contrat, plus spécifiques, l'url est plus
complexe (règles de réécriture à changer éventuellement) :
http://wxs.ign.fr/autoconf/api/autoConf/service/xml/CLE/id/LAYER_ID
Paramètre
valeur
LAYER_ID
L'identifiant unique de la couche agrégée
CLE
La clé de contrat API principale détenue par l’utilisateur (optionnel)
L'identifiant de la couche est l'id qui est retourné par la première opération du service.
Les couches agrégées sont repérables grâce au champ aggregate="aggregate" dans la description
de la ressource, et le champ more="more" qui permet de savoir si la deuxième opération est
disponible pour cette ressource.
Exemple de requête :
http://wxs.ign.fr/autoconf/id/GEOGRAPHICALGRIDSYSTEMS.MAPS.3D$GEOPORTAI
L:OGC:WMTS@aggregate
Remarques :
•
d'autres ressources semblent disponibles pour cette deuxième opération du service, mais ne
sont pas identifiées comme telles dans la réponse de la première autoconf (pas de champ
more ou aggregate).
•
Actuellement, les ressources agrégées sont disponibles uniquement pour le service d'autoconfiguration (les ressources WMTS ne sont par exemple pas encore accessibles en
WMTS), et seules certaines d'entre elles peuvent être associées à une clé de contrat API , et
donc accessibles par un utilisateur.
Réponse du service :
La réponse du service est un fichier XML dont la structure hérite du standard OGC Web Map
Context. Des informations plus détaillées sur ce standard peuvent être trouvées sur le site de
l'OGC : http://www.opengeospatial.org/standards/wmc.
•
Comportement sans clé : le service retourne l’intégralité des couches ou agrégats ou
éléments d’agrégats disponibles et les paramètres API pour chaque couche ;
• Comportement avec une clé : le service retourne l’intégralité des couches disponibles pour la
clé et les paramètres API pour chaque couche ;
• Comportement avec plusieurs clés : le service retourne l’intégralité des couches disponibles
pour les clés et les paramètres API pour chaque couche ;
• Comportement avec une clé ou plusieurs clés invalides : le service renvoie une exception
62/94
'La clé est invalide ou ne dispose d'aucun droit'.
Le paramètre output=json permet l'encapsulation de la réponse dans un objet JSON, du type :
{
http : {
status : code http de la réponse du service (200, 403, ...)
error :
},
xml : 'réponse brute du service'
}
Mise en cache des informations
Afin de répondre à des exigences de performance, un cache a été mis en place devant le service.
Ainsi, les réponses de l'auto-configuration pour une couche donnée sont stockées dans le cache dès
qu'elles ont été requêtées une fois. Les réponses suivantes sont ainsi retournées rapidement sans
sollicitation du service.
Dès qu'une publication de ressource a lieu, le cache expire et les nouvelles requêtes arrivant lancent
la régénération des réponses XML et la mise en cache.
Structure des données :
La structure de la réponse est la même pour la première et la deuxième opération du service. Dans
le cas de la deuxième opération, seules les couches agrégées de la ressource interrogée sont
détaillées.
La structure générale est la suivante :
ViewContext
> General
> Window
> BoundingBox
> Title
> Extension
> gpp:General
> gpp:Theme
> gpp:defaultGMLGFIStyleUrl
> gpp:Territories
> gpp:Territory
> gpp:defaultCRS
> gpp:AdditionalCRS
> gpp:AdditionalCRS
> (...)
> gpp:BoundingBox
> sld:MinScaleDenominator
> sld:MaxScaleDenominator
> gpp:Resolution
> gpp:Center
> gpp:x
> gpp:y
> gpp:DefaultLayers
> gpp:DefaultLayer
> gpp:DefaultLayer
> (...)
> gpp:Territory
63/94
> (...)
> gpp:TileMatrixSets
> wmts:TileMatrixSet
> ows:Identifier
> ows:SupportedCRS
> wmts:TileMatrix
> ows:Identifier
> wmts:ScaleDenominator
> wmts:TopLeftCorner
> wmts:TileWidth
> wmts:TileHeight
> wmts:MatrixWidth
> wmts:MatrixHeight
> gpp:Resolutions (*)
> gpp:Services
> Server
> OnlineResource
> LayerList
> Layer
> Server
> OnlineResource
> Name
> Title
> Abstract
> SRS
> FormatList
> Format
> StyleList
> Style
> Name
> Title
> DimensionList
> Dimension
> Extension
> gpp:Layer
> gpp:Constraints
> gpp:Thematics
> gpp:Thematic
> gpp:InspireThematics
> gpp:InspireThematic
> gpp:BoundingBox
> gpp:AdditionalCRS
> gpp:Originators
> gpp:Originator
> gpp:Attribution
> gpp:Logo
> gpp:URL
> gpp:Constraints
> gpp:Constraint
> gpp:CRS
> gpp:BoundingBox
> gpp:Legends
> gpp:Legend
64/94
> gpp:LegendURL
> OnlineResource
> gpp:QuickLook
> OnlineResource
> wmts:TileMatrixSetLink
> wmts:TileMatrixSet
> wmts:TileMatrixSetLimits
> wmts:TileMatrixLimits
> wmts:TileMatrix
> wmts:MinTileRow
> wmts:MaxTileRow
> wmts:MinTileCol
> wmts:MaxTileCol
> gpp:MetadataURL
> OnlineResource
> gpp:Keys
> gpp:Key
> (…)
(*) ces résolutions sont toujours celles correspondant au CRS WGS84 (EPSG 4326).
65/94
Schéma des données renvoyées par le service
66/94
67/94
Service de Géocodage
Le service de géocodage du Géoportail est basé sur le standard OpenLS (version 1.2).
Il est disponible à l'url suivante :http://wxs.ign.fr/CLE_API/geoportail/ols?
Il se décline sous deux formes : directe et inverse.
Géocodage Direct
Le géocodage direct permet de :
- déterminer la position d'un localisant, ou de lister plusieurs positions pouvant correspondre à ce
localisant
- d'indiquer le nombre de positions pouvant correspondre au localisant
- de donner des informations sur la qualité des positions trouvées.
- classer les résultats en fonction de leur pertinence.
Les requêtes peuvent être envoyées soit en HTTP POST ou GET. Dans ce dernier cas, le protocole
JSONP peut aussi être utilisé. La réponse retournée est en XML éventuellement encapsulée dans
une coquille JSON(P).
La structure de données relatives au géocodage direct manipulées par le service (requêtes et
réponses) est modélisée dans le schéma suivant.
68/94
Exemple de requête OpenLS :
<RequestHeader sessionID="" srsName="epsg:4326"/>
<Request maximumResponses="30"
methodName="GeocodeRequest" version="1.2"
requestID="">
<GeocodeRequest returnFreeForm="false">
<Address countryCode="StreetAddress">
<StreetAddress>
<Building number="36"/>
<Street>rue gérald rey</Street>
</StreetAddress>
<Place type="Municipality">arles</Place>
<PostalCode>13200</PostalCode>
<Department>13</Department>
<gml:envelope>
<gml:pos>43.682765684094534
4.604832911570827</gml:pos>
<gml:pos>43.686676004569826
4.614145541270513</gml:pos>
</gml:envelope>
</Address>
</GeocodeRequest>
</Request>
Illustration 1: Modèle du service de géocodage direct du Géoportail
Exemple de réponse OpenLS
<GeocodeResponseList numberOfGeocodedAddresses="1">
<GeocodedAddress>
<gml:Point>
<gml:pos>43.684079 4.607426</gml:pos>
</gml:Point>
<StreetAddress>
<Street>r gerald rey</Street>
</StreetAddress>
<Place type="Municipality">Arles</Place>
<Place type="Qualite">Plaque adresse</Place>
<Place type="ID">ADRNIVX_0000000264458864</Place>
<Place type="Departement">13</Place>
<Place
type="Bbox">4.607426;43.684079;4.607426;43.684079</Place>
<Place type="Commune">Arles</Place>
<Place type="INSEE">13004</Place>
<Place type="Territoire">FXX</Place>
<Place type="ID_TR">TRONROUT0000000040743444</Place>
</Address>
<GeocodeMatchCode accuracy="0.9495000000000001"
matchType="Street number"/>
</GeocodeResponseList>
Géocodage inverse
Le service de géocodage du Géoportail est basé sur le standard OpenLS (version 1.2).
Il est disponible à l'url suivante :http://wxs.ign.fr/CLE_API/geoportail/ols?
Il permet de déterminer des localisants (adresses, toponymes, parcelles cadastrales, etc) proches
d'un point donné, à l'intérieur d'un cercle, d'un rectangle ou d'un polygone, et de les classer en
fonction de leur proximité et de leur type (commune en premier lorsqu'il s'agit de toponyme).
La structure de données relatives au géocodage inverse manipulées par le service (requêtes et
réponses) est modélisée dans le schéma suivant.
70/94
Exemple de requête OpenLS
Exemple de réponse OpenLS
<ReverseGeocodeRequest>
<Position>
<gml:Point
xmlns:gml="http://www.opengis.net/gml">
<gml:pos>43.67981385532074
4.621169951900729</gml:pos>
</gml:Point>
<Polygon
xmlns="http://www.opengis.net/gml">
<exterior>
<LinearRing>
<pos>43.67965091175271
4.620933917507425</pos>
<pos>43.67965091175271
4.621405986294034</pos>
<pos>43.67997679844624
4.621405986294034</pos>
<pos>43.67997679844624
4.620933917507425</pos>
<pos>43.67965091175271
4.620933917507425</pos>
</LinearRing>
</exterior>
</Polygon>
</Position>
<ReverseGeocodeResponse>
<ReverseGeocodedLocation>
<gml:Point>
<gml:pos>43.679842 4.621130</gml:pos>
</gml:Point>
<StreetAddress>
<Street>r anibert</Street>
</StreetAddress>
<Place type="Municipality">Arles</Place>
<Place type="Qualite">Plaque adresse</Place>
<Place type="Departement">13</Place>
<Place
type="Bbox">4.621130;43.679842;4.621130;43.679842</Place>
<Place type="Commune">Arles</Place>
<Place type="INSEE">13004</Place>
<Place type="Territoire">FXX</Place>
</Address>
<xlsext:ExtendedGeocodeMatchCode>Street
number</xlsext:ExtendedGeocodeMatchCode>
<SearchCentreDistance value="5.44"/>
</ReverseGeocodedLocation>
</ReverseGeocodeResponse>
<ReverseGeocodePreference>StreetAddress</Rev
erseGeocodePreference>
</ReverseGeocodeRequest>
Illustration 2: Modèle du service de géocodage inverse du Géoportail
Service d'Autocomplétion
La plateforme Géoportail propose un service dit d'autocomplétion disponible à l'url suivante :
http://wxs.ign.fr/CLE_API/ols/apis/completion?
Il permet de :
- suggérer des localisants (adresses ou des toponymes) probables à partir d'une chaine de caractères
incomplète.
- filtrer les localisants proposés par territoire ou zone géographique,
- classer les résultats en fonction de leur pertinence.
Les requêtes sont envoyées en GET. La réponse retournée est en JSON. Le protocole JSONP peut
être utilisé.
72/94
Exemple de réponse
Exemple de requête :
{
"status":"OK",
"results":[{
"country":"StreetAddress",
"city":"Saint-Malo",
"x":-2.004141,
"y":48.655722,
"zipcode":"35400",
"street":"2 av pasteur",
"classification":7,
"kind":"",
"fulltext":
"2 av pasteur, 35400 Saint-Malo"
}]
http://wxs.ign.fr/VOTRE_LICENCE/ols/apis/completi
on?text=2%2C%20avenue%20pasteur%20saint
%20m&type=StreetAddress&maximumResponses=1
}
Illustration 3: Modèle du service d'autocomplétion
Service de calcul altimétrique
La plate-forme Géoportail met en œuvre un service dit d'altimétrie qui permet de retourner les
altitudes en un ou plusieurs points ou de déterminer un ensemble d'altitudes le long d'un tracé afin
d'obtenir le profil altimétrique de ce tracé.
Principe du service de calcul altimétrique
Le service de calcul altimétrique du Géoportail repose sur une API REST et sur le standard OGC
Web Processing Service (WPS – version 1.0.0). Il y a donc deux manières d'interroger le service :
via l'API REST ou via la norme WPS.
Il permet de :
•
retourner les altitudes d'un ou plusieurs points
•
déterminer un ensemble d'altitudes le long d'un tracé afin d'obtenir le profil altimétrique de
ce tracé.
Comme l'accès au service de calcul altimétrique est protégé par le contrôle des droits d'accès, l'URL
de la requête doit contenir la clef associée au contrat qui autorise l'accès aux ressources du service
altimétrique.
Détermination de l'altitude d'un ou plusieurs points
1. Accès au service
- API REST
http://wxs.ign.fr/CLE/alti/rest/elevation.{format}?
où :
CLE correspond à la clé de contrat API,
format désigne le format de récupération de la réponse : les formats disponibles sont XML et
JSON.
Les requêtes peuvent être envoyées en GET.
•
•
- Norme WPS
On accède au service via l'URL :
http://wxs.ign.fr/CLE/alti/wps?service=WPS&version=1.0.0
Où CLE est la clé de contrat API.
Les requêtes peuvent être envoyées en HTTP POST ou GET, et la réponse peut être récupérée en
XML ou en JSON. Par défaut (si le format n'est pas spécifié), la réponse est retournée en JSON.
Dans le cas d'une requête GET, on peut aussi utiliser le protocole JSONP.
2. Paramètres en entrée
Les paramètres suivants sont communs aux différentes méthodes d'interrogation du service
altimétrique, seule la manière dont ils sont spécifiés diffère.
74/94
Paramètre
Type
Opt.
Valeur
lon
Liste de
décimaux
Obligatoire Liste des longitudes des points (crs:84) dont on veut
(une au
connaître les altitudes, délimitées au choix par des
minimum) virgules, points-virgules, ou barres verticales (''|'').
Maximum 50.
lat
Liste de
décimaux
Obligatoire Liste des latitudes des points (crs:84) dont on veut
(une au
connaître les altitudes, délimitées par le même
minimum) caractère que les longitudes. Autant de lat que de lon
(ci-dessus), et maximum 50.
delimiter
Texte
Optionnel
Caractère utilisé pour séparer les latitudes et
longitudes dans leurs listes respectives.
Par défaut : barre verticale ('' | '').
zonly
Booléen
Optionnel
Si ce paramètre vaut 'true', le service renverra
uniquement un tableau contenant les altitudes des
points demandés.
S'il vaut true, le service renverra une réponse
étendue (cf. ci-dessous).
Par défaut : vaut false.
indent
Booléen
Optionnel
Booléen qui indique si la réponse sera indentée ou
non.
Par défaut : vaut false
crs
texte
Optionnel
Projection des coordonnées en sortie.
La valeur par défaut est 'CRS:84'.
En réalité, ce paramètre ne semble pas être
fonctionnel, le résultat en sortie est identique si on
spécifie un crs différent...
Les paramètres suivants ne peuvent être utilisés que dans le cas d'une requête GET (REST ou
WPS) :
Paramètre
Type
Opt.
Valeur
output
Texte
Optionnel
Permet de spécifier le format en sortie (XML ou
JSON). Particulièrement utile si l'on veut encapsuler
la réponse XML dans une coquille JSON.
On interroge alors le service en XML (dans l'url), et
le paramètre output=json.
callback
Texte
Optionnel
Nom de la fonction de traitement de la réponse en
JSON (natif ou xml encapsulé).
Ce paramètre est nul par défaut.
Le paramètre suivant ne peut être utilisé que dans le cas d'une requête via la norme WPS (GET ou
POST) :
Paramètre
format
Type
texte
Opt.
Optionnel
Valeur
Permet de spécifier le format de sortie (XML ou
JSON).
75/94
Paramètre
Type
Opt.
Valeur
Par défaut, c'est le format JSON qui sera utilisé.
3. Structure de la requête
- API REST
Les paramètres ci-dessus sont passés à la suite de l'URL spécifiée du service, séparés par le
caractère '&'.
Exemple :
http://wxs.ign.fr/CLE/alti/rest/elevation.xml?
lon=0.2367,2.1570&lat=48.0551,46.6077&delimiter=,&indent=true
- Norme WPS
Dans le cas de la méthode GET, plusieurs paramètres doivent être passés dans l'URL : request,
identifier, datainputs et rawdataoutputs. Deux autres paramètres sont optionnels : output
et callback (pour une encapsulation JSONP).
C'est dans le paramètre datainputs que l'on va spécifier les paramètres ci-dessus, séparés par des
points-virgules (lon, lat, delimiter, format, ident, zonly, crs).
Exemple :
&request=Execute
&identifier=gs:WPSElevation
&datainputs=lon=0.2367|2.1570;lat=48.0551|46.6077;format=xml;indent=true
&rawdataoutput=result
&output=json
&callback=loadJSONP
Dans le cas de la méthode POST, le corps de la requête doit avoir une structure semblable à la
suivante :
<?xml version="1.0" encoding="UTF-8"?>
<wps:Execute version="1.0.0" service="WPS"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.opengis.net/wps/1.0.0"
xmlns:wfs="http://www.opengis.net/wfs"
xmlns:wps="http://www.opengis.net/wps/1.0.0"
xmlns:ows="http://www.opengis.net/ows/1.1"
xmlns:gml="http://www.opengis.net/gml"
xmlns:ogc="http://www.opengis.net/ogc"
xmlns:wcs="http://www.opengis.net/wcs/1.1.1"
xmlns:xlink="http://www.w3.org/1999/xlink"
xsi:schemaLocation="http://www.opengis.net/wps/1.0.0
http://schemas.opengis.net/wps/1.0.0/wpsAll.xsd">
<ows:Identifier>gs:WPSElevation</ows:Identifier>
<wps:DataInputs>
<wps:Input>
<ows:Identifier>lon</ows:Identifier>
<wps:Data>
<wps:LiteralData>0.2367|2.1570</wps:LiteralData>
</wps:Data>
76/94
</wps:Input>
<wps:Input>
<ows:Identifier>lat</ows:Identifier>
<wps:Data>
<wps:LiteralData>48.0551|46.6077</wps:LiteralData>
</wps:Data>
</wps:Input>
<wps:Input>
<ows:Identifier>format</ows:Identifier>
<wps:Data>
<wps:LiteralData>xml</wps:LiteralData>
</wps:Data>
</wps:Input>
<wps:Input>
<ows:Identifier>indent</ows:Identifier>
<wps:Data>
<wps:LiteralData>true</wps:LiteralData>
</wps:Data>
</wps:Input>
</wps:DataInputs>
<wps:ResponseForm>
<wps:RawDataOutput>
<ows:Identifier>result</ows:Identifier>
</wps:RawDataOutput>
</wps:ResponseForm>
</wps:Execute>
4. Paramètres en sortie
Quel que soit le mode d'interrogation du service, la réponse est une liste d'éléments, qui contiennent
respectivement les valeurs d'altitude déterminées pour les points demandés, dans l'ordre dans lequel
les points ont été fournis.
• réponse simple : uniquement les altitudes (z)
•
réponse étendue : la longitude (lon) et la latitude (lat) du point, l’altitude du point considéré
(z) en mètres, et la précision de la valeur au point considéré (acc).
Paramètre
Type
Opt.
Valeur
lon
Nombre
décimal
Optionnel
Longitude du point fourni
lat
Nombre
décimal
Optionnel
Latitude du point fourni
z
Nombre
décimal
Obligatoire Altitude déterminée du point fourni
acc
Nombre
Optionnel
Précision de la valeur au point considéré.
décimal
Ces paramètres sont présentés différemment selon le format de sortie spécifié (XML, JSON).
Exemple de réponse XML
La réponse est une liste d'éléments elevation contenant les informations des points demandés.
<elevations>
77/94
<elevation>
<lon>0.2367</lon>
<lat>48.0551</lat>
<z>96.35</z>
<acc>2.5</acc>
</elevation>
<elevation>
<lon>2.157</lon>
<lat>46.6077</lat>
<z>207.52</z>
<acc>2.5</acc>
</elevation>
</elevations>
Exemple d'encapsulation de la réponse XML dans une coquille JSON
La réponse est un objet JSON, contenant la réponse XML ci-dessus dans sa propriété "xml".
{
"http":{"status":200,"error":null},
"xml":"<elevations><elevation><lon>0.2367</lon><lat>48.0551</lat><z>96.35</z><a
cc>2.5</acc></elevation><elevation><lon>2.157</lon><lat>46.6077</lat><z>207.52<
/z><acc>2.5</acc></elevation></elevations>"
}
Exemple de réponse JSON
La réponse est un tableau elevations contenant les informations des points demandés.
{"elevations": [
{
"lon": 0.2367,
"lat": 48.0551,
"z": 96.35,
"acc": 2.5
},
{
"lon": 2.157,
"lat": 46.6077,
"z": 207.52,
"acc": 2.5
}
]}
Exemple de réponse via le protocole JSONP (réponse du service en XML)
La réponse est un objet JSON contenant d'une part les informations sur la requête HTTP, et d'autre
part la réponse XML, encapsulée dans une chaîne de caractères.
loadJSON({
"http":{
"status":200,
"error":null
},
"xml":"<elevations><elevation><lon>0.2367</lon><lat>48.0551</lat><z>96.35<
/z><acc>2.5</acc></elevation><elevation><lon>2.157</lon><lat>46.6077</lat><z>20
7.52</z><acc>2.5</acc></elevation></elevations>"
})
78/94
5. Messages d'erreur
En cas d'erreur du service (code HTTP différent de 200, par exemple si l'URL est invalide (not
found) ou si la clé est invalide (forbidden)), la réponse est au format XML.
S'il manque des paramètres (lon et lat notamment), ou s'ils ne sont pas correctement spécifiés, le
service renvoie une réponse en HTTP 200, contenant le message d'erreur. Dans le cas de l'API
REST, la réponse est au format XML ou JSON, selon le format spécifié (Elevation.xml ou
Elevation.json). Dans le cas de la norme WPS, la réponse est au format XML, et contient
l'exception Java retournée.
Détermination du profil altimétrique d'une courbe
1. Accès au service
- API REST
http://wxs.ign.fr/CLE/alti/rest/elevationLine.{format}?
où les formats disponibles sont toujours XML et JSON, et CLE la clé de contrat API.
Les requêtes peuvent être envoyées en GET.
- Norme WPS
L'URL d'accès au service est la même que dans le cas de détermination d'altitudes simples :
où CLE est la clé de contrat API.
Les requêtes peuvent être envoyées en HTTP POST ou GET, et la réponse peut être récupérée en
XML ou en JSON. Dans le cas d'une requête GET, on peut aussi utiliser le protocole JSONP pour
encapsuler la réponse XML dans une coquille JSON.
2. Paramètres en entrée
Les paramètres en entrée sont en partie les mêmes que pour déterminer de simples altitudes de
points : lon, lat, delimiter, indent, crs, output, callback. (Il n'est plus possible de ne
demander que l'altitude avec zonly).
S'y ajoute le paramètre suivant sampling :
Paramètre
sampling
Type
entier
Opt.
Optionnel
Valeur
Nombre de points constituant l’échantillonnage,
compris entre 2 et 5000.
Par défaut, ce paramètre vaut 3.
3. Structure de la requête
Différences par rapport au premier cas (détermination d'altitudes de points fournis) :
- API REST
La requête est similaire au premier cas, le paramètre sampling peut être ajouté à la liste des
paramètres.
Exemple :
79/94
http://wxs.ign.fr/CLE/alti/rest/elevationLine.json?
sampling=5&lon=0.2367|2.1570|4.3907&lat=48.0551|46.6077|43.91
- Norme WPS
Dans le cas de la méthode GET, le paramètre identifier doit être modifié si l'on souhaite
bénéficier de l'échantillonnage : identifier=WPSLineElevation et non plus WPSElevation.
De plus, le paramètre sampling peut être ajouté dans datainputs.
Exemple :
http://wxs.ign.fr/CLE/alti/wps? service=WPS&version=1.0.0
&request=Execute
&identifier=gs:WPSLineElevation
&datainputs=lon=0.2367|2.1570;lat=48.0551|46.6077;format=xml;
indent=true;sampling=5
&rawdataoutput=result
&output=json
&callback=loadJSONP
Dans le cas de la méthode POST, il faut de même préciser WPSLineElevation comme identifier,
et spécifier éventuellement le paramètre sampling comme nouvel élément input.
Exemple (extrait) :
<wps:Execute version="1.0.0" service="WPS"
(…)
<ows:Identifier>gs:WPSLineElevation</ows:Identifier>
<wps:DataInputs>
(…)
<wps:Input>
<ows:Identifier>sampling</ows:Identifier>
<wps:Data>
<wps:LiteralData>5</wps:LiteralData>
</wps:Data>
</wps:Input>
</wps:DataInputs>
<wps:ResponseForm>
<wps:RawDataOutput>
<ows:Identifier>result</ows:Identifier>
</wps:ResponseForm>
</wps:Execute>
4. Paramètres en sortie
La réponse du service a la même structure que si l'on souhaitait récupérer seulement les altitudes
des points fournis : elle présente cette fois les informations de l'ensemble des points constituant
l'échantillonnage (lon, lat, z et acc).
Exemple de réponse JSON :
La réponse contient les informations de 5 points d'échantillonnage (seulement 3 points spécifiés
dans la requête).
{"elevations": [
{"lon": 0.2367,"lat": 48.0551,"z": 96.35,"acc": 2.5},
80/94
]}
{"lon":
{"lon":
{"lon":
{"lon":
1.20996836,"lat": 47.33546691,"z": 62.06,"acc": 2.5},
2.157,"lat": 46.6077,"z": 207.52,"acc": 2.5},
3.30030144,"lat": 45.26446777,"z": 638.09,"acc": 2.5},
4.3907,"lat": 43.91,"z": 182.6,"acc": 2.5}
Modèle de données du service altimétrique
Modèle des données renvoyées par le service altimétrique
81/94
Service de calcul d'itinéraires
Le service de calcul d'itinéraires déployé sur la plateforme géoportail permet de déterminer un
itinéraire entre un point de départ et un point d'arrivée en utilisant les données routières issues de la
BDTopo enrichies d'informations issues d'autres bases de données IGN.
Syntaxe, protocoles d'accès
Le service est interogeable selon le standard OpenLS version 1.2 dont il implémente la partie
« Route Service ». Des extensions ont été définies pour répondre aux spécificités de la solution
serveur et des données utilisées pour la mise en œuvre du service.
Il est aussi accessible selon une syntaxe propriétaire via une API REST.
Il est accessible en HTTP GET et POST.
Lorsqu'on utilise l'interface OpenLS, les requêtes sont exprimées en XML. Dans tous les cas
(OpenLS ou API REST), les réponses sont exprimées en XML.
Comme pour les autres services répondant en XML, l'adjonction aux requêtes du paramètre
output=JSON permet l'encapsulation de la réponse dans une coquille JSON décrite précédemment.
L'ajout supplémentaire du paramètre callback permet de mettre en œuvre le protocole JSONP
comme décrit précédemment.
Données
Requête
Une requête envoyée au service de calcul d'itinéraire comprend les éléments suivants :
Paramètre
description
routePreference
Mode de caclul : « fastest », « shortest » ou « pedestrian »
startPoint
Point de départ (coordonnées exprimées en WGS84G)
endPoint
Point d'arrivée (coordonnées)
viaPoint
Liste de points intermédiaires
avoidFeature
Liste de types de tronçons à ne pas emprunter (« tollway »,
« tunnel » ou « bridge »)
vehicle
Type de véhicule utilisé (« car ») : cette valeur détermine le
profil de véhicule utilisé pour le calcul par le service
(tronçons autorisés / non autorisés, vitesses par
tronçons, ...)
expectedStartTime
Date et heure de départ
provideGeometry
Indique si l'on souhaite avoir la géométrie associée à
chaque instruction dans la réponse (duplication par rapport
à l'itinéraire complet)
provideBoundingBox
Indique si l'on souhaite avoir les emprises géométriques
(rectangle englobant) de chacune des instructions
distanceUnit
Unité dans lesquelles la distance est exprimée (« m » ou
« km »)
82/94
Exemple de requête exprimée en OpenLS :
<xls:XLS xmlns:xls="http://www.opengis.net/xls"
xmlns:sch="http://www.ascc.net/xml/schematron"
xmlns:gml="http://www.opengis.net/gml"
xmlns:xlsext="http://www.opengis.net/xlsext"
xsi:schemaLocation="http://www.opengis.net/xls
http://schemas.opengis.net/ols/1.1.0/RouteService.xsd" version="1.1"
xls:lang="en">
<xls:RequestHeader/>
<xls:Request methodName="RouteRequest" requestID="123456789" version="1.1">
<xls:DetermineRouteRequest distanceUnit="KM">
<xls:RoutePlan>
<xls:RoutePreference>Fastest</xls:RoutePreference>
<xlsext:vehicle name="Car" />
<xls:WayPointList>
<xls:StartPoint><xls:Position><gml:Point srsName="EPSG:4326"><gml:pos>2.29993
48.87228</gml:pos></gml:Point></xls:Position></xls:StartPoint>
<xls:EndPoint><xls:Position><gml:Point srsName="EPSG:4326"><gml:pos>-1.53604
47.21548</gml:pos></gml:Point></xls:Position></xls:EndPoint>
</xls:WayPointList>
</xls:RoutePlan>
<xls:RouteInstructionsRequest provideGeometry="true"/>
<xls:RouteGeometryRequest/>
</xls:DetermineRouteRequest>
</xls:Request>
</xls:XLS>
Réponse
Une réponse du service comprend les informations suivantes :
Propriété
Description
totalTime
Durée totale de l'itinéraire
totalDistance
Longueur de l'itinéraire (exprimée dans l'unité demandée
dans la requête)
boundingBox
Emprise de l'itinéraire
routeGeometry
Géométrie de l'itinéraire (liste de segments)
RouteInstructionList : liste des instructions le long de l'itinéraire. Une instruction comprend les
éléments suivants.
duration
Durée de l'instruction
distance
Distance concernée par l'instruction
description
Code de l'instruction :
- F : tout droit
- B : demi-tour
- L : tourner à gauche
- R : tourner à droite
- BL : tourner très à gauche
- BR : tourner très à droite
83/94
Propriété
Description
- FL : tourner légèrement à gauche
- FR : tourner légèrement à droite
- round_about_entry : entrée rond-point
- round_about_exit : sortie rond-point:
instruction
Texte de l'instruction (traduction du code + nom de la rue
concernée)
boundingBox
Emprise de l'instruction
routeInstructionGeometry
Géométrie (liste de points) de l'uinstruction
Exemple de réponse exprimée en OpenLS :
<XLS version="1.2" xsi:schemaLocation="http://www.opengis.net/xls
http://schemas.opengis.net/ols/1.2/olsAll.xsd">
<ResponseHeader/>
<Response requestID="123456789" version="1.2">
<DetermineRouteResponse>
<RouteSummary>
<BoundingBox>
<gml:pos>2.42339 48.844522</gml:pos>
<gml:pos>2.440009 48.84741</gml:pos>
</BoundingBox>
<TotalTime>PT4M54.290S</TotalTime>
<TotalDistance uom="KM" value="1.65902"/>
</RouteSummary>
<RouteGeometry>
<gml:LineString>
<gml:pos>2.423390 48.844620</gml:pos>
<gml:pos>2.423403 48.844619</gml:pos>
<gml:pos>2.423439 48.844772</gml:pos>
<gml:pos>2.423659 48.845732</gml:pos>
(...)
<gml:pos>2.439979 48.847082</gml:pos>
<gml:pos>2.439979 48.847122</gml:pos>
<gml:pos>2.439989 48.847202</gml:pos>
<gml:pos>2.440009 48.847362</gml:pos>
<gml:pos>2.439656 48.847384</gml:pos>
<gml:pos>2.439660 48.847410</gml:pos>
</gml:LineString>
</RouteGeometry>
<RouteInstructionsList lang="fr">
<RouteInstruction duration="PT32S">
<BoundingBox>
<gml:pos>2.423390 48.844619</gml:pos>
<gml:pos>2.423699 48.845932</gml:pos>
</BoundingBox>
<distance uom="KM" value="0.148"/>
<Instruction> AVENUE PASTEUR</Instruction>
<RouteInstructionGeometry>
<gml:LineString>
<gml:pos>2.423390 48.844620</gml:pos>
<gml:pos>2.423403 48.844619</gml:pos>
<gml:pos>2.423439 48.844772</gml:pos>
<gml:pos>2.423659 48.845732</gml:pos>
<gml:pos>2.423699 48.845932</gml:pos>
</gml:LineString>
</RouteInstructionGeometry>
84/94
</RouteInstruction>
<RouteInstruction description="R" duration="PT2M39S">
<BoundingBox>
<gml:pos>2.423699 48.844602</gml:pos>
<gml:pos>2.438659 48.845932</gml:pos>
</BoundingBox>
<Instruction>Tourner à droite AVENUE DE PARIS</Instruction>
<gml:LineString>
<gml:pos>2.423699 48.845932</gml:pos>
<gml:pos>2.424199 48.845892</gml:pos>
(...)
<gml:pos>2.437909 48.844652</gml:pos>
<gml:pos>2.438659 48.844602</gml:pos>
</gml:LineString>
</RouteInstruction>
(...)
<RouteInstruction description="L" duration="PT25S">
<BoundingBox>
<gml:pos>2.439656 48.847362</gml:pos>
<gml:pos>2.440009 48.847410</gml:pos>
</BoundingBox>
<Instruction>Tourner à gauche null</Instruction>
<gml:LineString>
<gml:pos>2.440009 48.847362</gml:pos>
<gml:pos>2.439656 48.847384</gml:pos>
<gml:pos>2.439660 48.847410</gml:pos>
</gml:LineString>
</RouteInstruction>
</RouteInstructionsList>
</DetermineRouteResponse>
</Response>
</XLS>
85/94
Service de calcul d'isochrones / isodistances
Le service de calcul d'isochrones / isodistances déployé sur la plateforme géoportail permet de
déterminer un ensemble de lieux que l'on peut atteindre à partir d'un point et selon un temps
(isochrone) ou une distance (isodistance) donnés en utilisant les données routières issues de la
BDTopo enrichies d'informations issues d'autres bases de données IGN.
Le service est interogeable selon une syntaxe propriétaire via une API de type REST.
Il est accessible en HTTP GET et POST.
L'interface REST permet d'émettre des requêtes en GET dans l'URL ou en POST en XML ou en
JSON. La réponse est exprimée soit en XML soit directement en JSON.
En POST / XML, une encapsulation de la requête dans une enveloppe SOAP est possible.
Lorsque la réponse est en XML, l'adjonction aux requêtes du paramètre output=JSON permet
l'encapsulation de la réponse dans une coquille JSON décrite précédemment.
L'ajout supplémentaire du paramètre callback permet de mettre en œuvre le protocole JSONP
comme décrit précédemment.
Données
Requête
Une requête envoyée au service de calcul d'isochrones / isodistances comprend les éléments
suivants :
Paramètre
description
id
Identifiant de la requête
location
Point d'arrivée ou de départ.
srs
Système de coordonnées du point de départ / arrivée
graphName
Nom du graphe à utiliser : une seule valeur possible
correspondant à BD-TOPO.
profileName
Profil de véhicule : seul le profil « voiture » disponible.
rejectFlags
Critères d'exclusion (« Toll » : péage, « Tunnel »,
« Bridge »)
type
Type de calcul attendu : « time », si on souhaite un calcul
d'isochrone ; « distance » si on souhaite un calcul
d'isodistance.
time
Durée maximum du trajet, exprimée en seconde (utilisée
pour les isochrones).
distance
Distance maximum du trajet, exprimée en metres (utilisée
pour les isodistances).
reverse
Indique si le point « location » sert de de destination
(« true ») ou de point de départ (« false »)
86/94
Paramètre
description
smoothing
Indique si on souhaite un lissage de la géométrie retournée
(« true »).
holes
Indique si on acepte des trous dans la géométrie retournée
(« true »).
Exemple de requête exprimée en XML :
<isochronRequest>
<id>1</id>
<location>
<x>2.324230</x>
<y>48.803256</y>
</location>
<srs></srs>
<graphName></graphName>
<profileId></profileId>
<profileName></profileName>
<rejectFlags></rejectFlags>
<rejectFlags></rejectFlags>

<exclusions>
<exclusion></exclusion>
<exclusion></exclusion>

</exclusions>
<method></method>
<time>50</time>
<distance></distance>
<reverse></reverse>
<smoothing></smoothing>
<holes></holes>
</isochronRequest>
Réponse
Une réponse du service comprend les informations suivantes :
Propriété
Description
id
Identifiant de l'iscchrone / distance
location
Point de départ ou d'arrivée de l'isochrone / distance
srs
Système de coordonnées des coordonnées en sortie
time
Durée maximum pour l'isochrone
distance
Distance maximum pour l'isodistance
wktGeometry
Géométrie de l'isochrone / distance, au format WKT.
status
Statut de la réponse
Exemple de réponse formatée en XML :
<isochronResult>
<status>OK</status>
87/94
<id>1</id>
<location>2.32423,48.803256</location>
<srs/>
<time>50</time>
<wktGeometry>POLYGON ((2.324091 48.803926, 2.324735 48.803926, 2.324735
48.804354, 2.322804 48.804354, 2.322804 48.803497, 2.321516 48.803497, 2.321516
48.803926, 2.320873 48.803926, 2.320873 48.803497, 2.320229 48.803497, 2.320229
48.804354, 2.320873 48.804354, 2.320873 48.805211, 2.320229 48.805211, 2.320229
48.806069, 2.320873 48.806069, 2.320873 48.80564, 2.321516 48.80564, 2.321516
48.806069, 2.32216 48.806069, 2.32216 48.805211, 2.322804 48.805211, 2.322804
48.80564, 2.323447 48.80564, 2.323447 48.806497, 2.324091 48.806497, 2.324091
48.806069, 2.324735 48.806069, 2.324735 48.806497, 2.325379 48.806497, 2.325379
48.807354, 2.326022 48.807354, 2.326022 48.80864, 2.326666 48.80864, 2.326666
48.806926, 2.326022 48.806926, 2.326022 48.80564, 2.32731 48.80564, 2.32731
48.805211, 2.328597 48.805211, 2.328597 48.804354, 2.327954 48.804354, 2.327954
48.804783, 2.326666 48.804783, 2.326666 48.805211, 2.326022 48.805211, 2.326022
48.804354, 2.326666 48.804354, 2.326666 48.803926, 2.326022 48.803926, 2.326022
48.803497, 2.325379 48.803497, 2.325379 48.803068, 2.324091 48.803068, 2.324091
48.803926))</wktGeometry>
</isochronResult>
88/94
Service de transformations de coordonnées (WCTS)
Le service de transformation de coordonnées de la plateforme Géoportail permet de transformer un
jeu de coordonnées d'un système de référence à un autre.
Le service est conforme au standard WPS de l’OGC http://www.opengeospatial.org/standards/wps
Il se base sur le document Inspire WCTS11
Conformément au standard WPS, il expose les opérations :
•
GetCapabilities : Permet de connaître les capacités du service
•
DescribeProcess : Permet d’obtenir la description d’un processus
•
Execute : qui permet d'effectuer les opérations spécifiques (processus) de transformation de
coordonnées :
◦ GetValidityArea : Permet d’obtenir la zone de validité d’un CRS.
◦ TransformCoordinates : Transforme des coordonnées.
Processus GetValidityArea
Requête
Exemple de requête POST pour GetValidityArea
<wps:Execute service="WPS" version="1.0.0"
xsi:schemaLocation="http://www.opengis.net/wps/1.0.0/wpsExecute_request.xsd">
<ows:Identifier>GetValidityArea</ows:Identifier>
<wps:DataInputs>
<wps:Input>
<ows:Identifier>CRS</ows:Identifier>
<wps:Data>
<wps:LiteralData>{crs}</wps:LiteralData>
</wps:Data>
</wps:Input>
</wps:DataInputs>
<wps:ResponseForm>
<wps:ResponseDocument lineage="{lineage}">
<wps:Output>
<ows:Identifier>ValidityArea</ows:Identifier>
</wps:Output>
</wps:ResponseDocument>

<wps:RawDataOutput>
11 http://inspire.ec.europa.eu/reports/ImplementingRules/network/Draft_Technical_Guidance_Coordinate_Transforma
tion_Services_v1.0.pdf
89/94
</wps:ResponseForm>
</wps:Execute>
Réponse
Réponse si « ResponseForm » est en mode « ResponseDocument » :
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<wps:ExecuteResponse xmlns:wps="http://www.opengis.net/wps/1.0.0"
xmlns:ns4="http://www.w3.org/1999/xlink" xml:lang="fr" version="1.0.0"
service="WPS">
<wps:Process wps:processVersion="1">
<ows:Identifier>GetValidityArea</ows:Identifier>
</wps:Process>
<wps:ProcessOutputs>
<wps:Output>
<wps:Data>
<wps:ComplexData>{-5.5,10.0,41.0,52.0}</wps:ComplexData>
</wps:Data>
</wps:Output>
</wps:ProcessOutputs>
</wps:ExecuteResponse>
Réponse si « ResponseForm » est en mode « RawDataOutput » :
{-5.5,10.0,41.0,52.0}
Processus TransformCoordinates
Requête
Exemple de requête POST pour TransformCoordinates
<wps:Execute service="WPS" version="1.0.0"
xsi:schemaLocation="http://www.opengis.net/wps/1.0.0/wpsExecute_request.xsd">
<ows:Identifier>TransformCoordinates</ows:Identifier>
<wps:DataInputs>

<wps:Input>
<ows:Identifier>SourceCRS</ows:Identifier>
<wps:Data>
<wps:LiteralData>{sourcecrs}</wps:LiteralData>
</wps:Data>
</wps:Input>

<wps:Input>
<ows:Identifier>TargetCRS</ows:Identifier>
<wps:Data>
<wps:LiteralData>{targetcrs}</wps:LiteralData>
90/94
</wps:Data>
</wps:Input>

<wps:Input>
<ows:Identifier>NadgridMode</ows:Identifier>
<wps:Data>
<wps:LiteralData>{nadgridmode}</wps:LiteralData>
</wps:Data>
</wps:Input>

<wps:Input>
<ows:Identifier>InputData</ows:Identifier>
<wps:Data>
<wps:ComplexData>
{points}
</wps:ComplexData>
</wps:Data>
</wps:Input>
</wps:DataInputs>
<wps:ResponseForm>
<wps:ResponseDocument lineage="{lineage}">
<wps:Output>
<ows:Identifier>TransformedData</ows:Identifier>
</wps:Output>
</wps:ResponseDocument>

<wps:RawDataOutput>
</wps:ResponseForm>
</wps:Execute>
Réponse
Réponse si « ResponseForm » est en mode « ResponseDocument » :
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<wps:ExecuteResponse xmlns:wps="http://www.opengis.net/wps/1.0.0"
xmlns:ns4="http://www.w3.org/1999/xlink" xml:lang="fr" version="1.0.0"
service="WPS">
<wps:Process wps:processVersion="1">
<ows:Identifier>TransformCoordinates</ows:Identifier>
</wps:Process>
<wps:ProcessOutputs>
<wps:Output>
<wps:Data>
<wps:ComplexData>
621202.7315498911, 6433917.946033287</wps:ComplexData>
</wps:Data>
</wps:Output>
</wps:ProcessOutputs>
</wps:ExecuteResponse>
91/94
Réponse si « ResponseForm » est en mode « RawDataOutput » :
621202.7315498911, 6433917.946033287
92/94

API Géoportail – Services Spécifications Fonctionnelles

Transcription

Documents pareils

quelques applis pour tablettes et smartphones utiles dans l

Etape 1. 1. Insérez le CD d`installation dans votre lecteur de CD

Espace Publique Numérique Bureau Information Jeunesse

Lire et écrire un enregistrement dans un fichier texte

les chaînes de caractères Application Program

Etape 1. 1. Insérez le CD d`installation dans votre lecteur

Peut-on encore toucher le complément optionnel de libre choix d

PIXMA MG3200 Guide d`installation

Etape 1. 1. Insérez le CD d`installation dans votre lecteur de CD