Exploiter les données : API, OData et OGDI

La Ville de Bordeaux a choisi la plateforme OGDI (OpenGovernment Data Initiative) pour déployer et proposer rapidement des données selon un protocole et des formats de données les plus ouverts et accessibles possibles. Toute la documentation est librement accessible sur internet.

Requêter OGDI

OGDI est une API qui utilise des services Web RESTful, des services Web implémentés à l'aide du protocole http et des principes REST, pour proposer des données à la consultation ou au téléchargement. Ce principe facilite beaucoup l'accès aux données pour les développeurs.

Le format de base des URLs pour requêter un service est la suivante :

http://odata.bordeaux.fr/v1/databordeaux/[dataset]?[query] où :

 odata.bordeaux.fr est le nom projet pour la publication du service ;

 databordeaux est le nom du conteneur (pour les ensembles de données mis à disposition par l’entrepôt de données) ;

 dataset est le nom du jeu de données ;

 query est l’ensemble des paramètres de la requête, exprimé en utilisant un sous-ensemble de la syntaxe de requête de WCF Data Services. 

NB : A noter qu'OGDI ne supporte actuellement que les options de requête de WCF Data Services $select et $top. La prochaine évolution, en cours de développement, intégrera des options de requêtes supplémentaires conformément au protocole odata.

L'ensemble des requêtes odata (incluant celles supportées par OGDI) sont disponibles sur le site http://www.odata.org/documentation/uri-conventions

A noter que si une propriété d'un ensemble de données a une valeur nulle, elle sera inexistante dans le résultat retourné par le service de données d’OGDI. Votre application doit donc prendre en compte la possible absence d'un champ dans le résultat retourné. 

 

Les formats de données

 Excel et CSV

Pour un plus grand confort d'utilisation, chaque table de données est téléchargeable dans son intégralité via les formats xls et csv. Ce dernier, encodé en utf8, peut-être ouvert dans tout éditeur de texte sans difficulté (open office TM, NotePad++); en revanche l'ouverture dans Excel(R) entrainera un affichage erroné des caractères accentués.

Ces formats sont téléchargeables mais ne peuvent pas être requêtés.

 

 AtomPub (pictogramme Atom sur le site)

Par défaut, OGDI retourne les données dans le format du protocole Odata (Open Data Protocol). Ce format étend le protocole largement utilisé Atom Pub et peut être utilisé par une variété de plateformes incluant .NET, Java, Ruby, PHP et Python. Différents exemples de code sont proposés sur la page de visualisation des données. 

ex : http://odata.bordeaux.fr/v1/databordeaux/sigBornes/?format=atom

 

 JSON 

Le service de données d’OGDI peut aussi retourner les données au format JSON (JavaScript Object Notation) qui peut être plus facilement exploitable depuis JavaScript ou autre technologie. Pour retourner des données au format JSON, il suffit d'ajouter format=json à votre requête. 

ex : http://odata.bordeaux.fr/v1/databordeaux/sigBornes/?format=json 

 

 JSONP 

Pour diminuer la vulnérabilité en terme de sécurité liée aux attaques de type scriptage intersite (cross-site scripting ou XSS en abrégé), généralement les navigateurs empêchent le JavaScript d'une page Web venant d'un domaine X de faire des requêtes http vers un autre domaine Y. Cela empêche tout code JavaScript hébergé sur un domaine d'effectuer des appels directs au service de données OGDI, mais il existe plusieurs techniques qui peuvent être utilisées comme la technique fondée sur des IFrames.  

OGDI fournit un support direct pour la technique JSONP. En utilisant cette technique, le service de données OGDI appelle la fonction de rappel (callback) que vous aurez spécifiée, passant le résultat de votre requête au format JSON comme format d'entrée. Pour utiliser cette technique, il convient de construire votre requête avec les paramètres additionnels format=json&callback=fonction_rappel, fonction_rappel étant le nom de votre fonction de rappel JavaScript définie dans la page émettant la requête. 

Vous pouvez consulter l'exemple de code JavaScript sur la page visualisation des données pour un exemple utilisant JSONP avec OGDI. Dans cet exemple, la fonction AdditionalDataLoaded() est la fonction de callback JSONP

 

 KML (données géographiques)

Un certain nombre de données proposées par la Ville contient des données géographiques, celles-ci sont disponibles dans deux colonnes 'Lat' et 'Long' en wgs84, ainsi que dans une colonne 'géométrie' en wkt wgs84 dans le cas des objets linéaires ou surfaciques.

Ces données peuvent être retournées dans le format KML (Keyhole Markup Language), rendant OGDI compatible avec des technologies de cartographie sur poste de travail ou sur le Web, comme Géoportail, Google Earth, Google Maps, Microsoft Bing Maps ou encore Yahoo! Maps. 

Pour cela, il suffit de rajouter format=kml à la requête.

ex : http://odata.bordeaux.fr/v1/databordeaux/sigBornes/?format=kml

A noter que, si l'ensemble de données ne contient pas de données de géolocalisation, une requête de type KML au service de données OGDI retournera un résultat vide. 

 

A propos de la pagination

Le service de données OGDI et le service sous-jacent de tables Windows Azure supportent la pagination pour les résultats d'un volume important. L’article MSDN Query Timeout et la Pagination  de la documentation Windows Azure fournit une description complète sur la façon dont OGDI et la plateforme Windows Azure prennent en charge la pagination. Vous pouvez vous référer également au code exemple "Pagination C#/ASP.NET " sur la page de visualisation des données, qui illustre comment gérer la pagination en utilisant la bibliothèque cliente WCF Data Services.

Par défaut seuls les 1000 premiers enregistrements sont renvoyés lors d'une requête. Le cas échéant, pour accéder aux enregistrements suivants, il convient d'utiliser les valeurs NextRowKey et NextPartitionKey qu’on retrouve dans le header http.

exemple de fonctionnement :

la 1ère requête sélectionne par exemple les 100 premiers éléments :

http://odata.bordeaux.fr/v1/databordeaux/[dataset]?$top=100&format=json ;

la 2nde requête, sélectionne les 100 suivants : http://odata.bordeaux.fr/v1/databordeaux/[dataset]?$top=100&NextPartitionKey=[valeur du header]&NextRowKey=[valeur du header]&format=json ;

Ainsi de suite jusqu’à ne plus trouver les headers x-ms-continuation-NextPartitionKey et x-ms-NextRowKey dans la réponse http.

NB : La nouvelle version 6 d'OGDI intègre le mot clé $top pour lequel il est possible de spécifier la valeur « all », ce qui permet de retourner l’ensemble des résultats d’un jeu de données (dataset) sans limiter le nombre de résultats. Pour plus de détails.

Bibliothèques clientes

Les développeurs utilisant Microsoft Visual Studio 2010 peuvent utiliser WCF Data Services pour accéder aux données ainsi exposées via des classes .NET. Avec Visual Studio, cela s’effectue simplement au travers de la fonctionnalité Add Service Reference (Ajouter une référence à un service) (voir les exemples avec le Microsoft Framework.NET sur la page de visualisation des données). Les interfaces de programmation Web proposées par le Kit de démarrage OGDI sont accessibles à une grande variété de technologies client. Ainsi, par exemple, les développeurs Java peuvent utiliser la bibliothèque Restlet Extension for OData, une composante du projet Open Source Restlet mettant à disposition un Framework léger REST pour Java. Les développeurs PHP peuvent tirer parti du kit de développement logiciel OData pour PHP. 

Dernières données
Citoyenneté et administration
22/06/2015
Cadre de vie
11/05/2015
Citoyenneté et administration
04/03/2015
Actualités

Where It's free référence les emplacements gratuits partout autour de vous !

Deux nouveaux jeux de données sur le portail opendata de Bordeaux 

Découvrez la nouvelle appli open data du territoire