Les données sont présentées sous divers formats. Vous trouverez dans le présent document de l'information, des conseils et des suggestions sur la façon d'utiliser certains des formats présentés dans le Portail de données ouvertes ainsi que la façon de travailler avec des interfaces de programmation d'applications (API).
De manière générale, les API s'adressent aux développeurs. Cette section donne des exemples dans lesquels on utilise différents outils et langages de programmation. Si vous ne possédez aucune expérience de la programmation, vous pouvez consulter le Portail de données ouvertes pour accéder aux jeux de données.
Sur cette page
Utilisation de la commande cURL
La commande cURL est un outil que l'on utilise sur la ligne de commande pour transférer des données en provenance ou à destination d'un serveur avec différents protoc9oles TCP/IP. Dans ce cas-ci, nous examinons la façon d'utiliser cette commande pour demander des données à une API HTTP RESTful. La commande peut être installée dans des plates-formes Windows, OSX ou Linux.
Windows
- Télécharger cURL (anglais seulement) ou
- Installer avec Cygwin (anglais seulement)
OSX
- Installer avec Macports
- Installer avec Homebrew ou
- Télécharger cURL (anglais seulement)
Linux
- Utiliser un gestionnaire de produit, tel YUM ou APT-GET, ou l'installateur de progiciel de l'interface graphique ou
- Télécharger cURL (anglais seulement).
Une fois la commande cURL installée, vous pouvez y accéder sur la ligne de commande en tapant simplement curl. Cette opération ne produit aucun résultat et permet uniquement de confirmer l'installation de la commande. Vous devez préciser, au minimum, l'URL de destination.
Il y a des API qui demandent certains paramètres, y compris les en-têtes HTTP. Pour réussir à communiquer avec certains API, vous devez également entrer des paramètres, y compris les en-têtes HTTP. Dans notre exemple, l'API permet de définir les en-têtes Accept et Accept-Language headers.
curl -H "Accept: application/json" -H "Accept-Language: en" \ "http://www.earthquakescanada.nrcan.gc.ca/api/v2/locations/" > data-raw.json
Par défaut, la commande cURL affiche sur l'écran de la console (STDOUT) la réponse en provenance de la destination. Dans l'exemple ci-dessus, la sortie est redirigée vers un fichier nommé data-raw.json qui contient le jeu de données anglais en format JSON.
Description accessible de la Figure 1
Saisie d'écran d'un fichier de réponse JSON en format brut minifié.
Dans la plupart des cas, la réponse est optimisée (minifiée) afin de réduire la taille du transfert de fichier (Figure 6). Vous pouvez utiliser un autre outil de ligne de commande, tel jsonpp (anglais seulement), pour formater les données en une sortie lisible par un humain (figure 7).
Description accessible de la Figure 2
Saisie d'écran d'un fichier de réponse JSON formaté en mode « pretty print » aux fins de lisibilité par un humain.
Utilisation des plugiciels de navigateur
La majorité des navigateurs offrent des plugiciels, outils utilisés pour interagir avec les API RESTful. Ces outils permettent de configurer les paramètres et les en-têtes, de récupérer une réponse et de visualiser les données. Ils peuvent être très utiles pour explorer rapidement les données d'API. Effectuez une recherche dans le répertoire de plugiciels de votre navigateur pour connaître ceux que vous pouvez utiliser.
Utilisation des langages de programmation
La majorité des langages de programmation modernes ont la capacité d'accéder aux ressources réseau, tels les services HTTP, soit en mode natif, ou par l'entremise de bibliothèques. Nous aborderons quelques exemples simples sur la façon de commencer à utiliser certains langages courants utilisés pour développer des applications Web et mobiles permettant d'accéder à une API RESTful.
Les programmes donnés en exemple ci-dessous illustrent la façon d'interroger une API et d'analyser la réponse JSON. La réponse est analysée pour afficher le nom du résultat et être répétée dans un des groupes de résultats.
PHP
L'exemple PHP suivant utilise la commande cURL :
<?php
/**
* Exemple simple de script PHP utilisé pour interroger une API.
*
* @license https://ouvert.canada.ca/fr/licence-du-gouvernement-ouvert-canada
*/
// Demander l'URL
$url = 'http://www.earthquakescanada.nrcan.gc.ca/api/earthquakes/';
// Request HTTP headers
$headers = array(
'Accept: application/json',
'Accept-Language: en'
);
// Configurer les options cURL
curl_setopt($cu, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($cu, CURLOPT_HTTPHEADER, $headers);
// Exécuter la demande cURL
$response = curl_exec($cu);
// Fermer l'objet cURL de manière appropriée
curl_close($cu);
// Afficher les données de réponse
if ($response) {
$json = json_decode($response);
echo "{$json->metadata->request->name->en}\n";
foreach($json->latest as $key=>$value) {
echo "{$key} -> {$value}\n";
}
}
Sortie :
Earthquake listings available 7d -> /api/v2/locations/7d.json 30d -> /api/v2/locations/30d.json 365d -> /api/v2/locations/365d.json
Python
L'analyseur Python requiert les deux bibliothèques (json et requests) utilisées dans l'exemple qui suit :
#!/usr/local/bin/python
# coding=utf-8
"""
Exemple simple de script Python utilisé pour interroger une API.
@license: https://ouvert.canada.ca/fr/licence-du-gouvernement-ouvert-canada
"""
import json
import requests
url = 'http://www.earthquakescanada.nrcan.gc.ca/api/earthquakes/'
options = { "Accept":"application/json", "Accept-Language":"en" }
response = requests.get(url, headers=options)
jdata = response.json()
print jdata['metadata']['request']['name']['en']
for (key, value) in jdata['latest'].items():
print key, "->", value
Sortie :
Earthquake listings available 365d -> /api/v2/locations/365d.json 7d -> /api/v2/locations/7d.json 30d -> /api/v2/locations/30d.json
Bibliothèque jQuery pour JavaScript
L'exécution de JavaScript dans un navigateur est assujettie à des restrictions concernant la sécurité des connexions à des sites Web tiers. Par défaut, les navigateurs interdisent les interrogations à distance, qu'ils considèrent être des scripts entre sites (Cross-Site Scripting (XSS)). Ces interrogations sont autorisées lorsque la réponse de l'API contient un en-tête HTTP Access-Control-Allow-Origin approprié qui permet les interrogations externes. Dans l'exemple qui suit, une connexion d'API est effectuée avec la bibliothèque jQuery (anglais seulement).
<!DOCTYPE html>
<html lang="en">
<head>
<title>Démonstration d'un appel d'API avec jQuery</title>
</head>
<body>
<div id="short"></div>
---
<div id="long"></div>
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
<script>
/**
* Exemple simple de script jQuery JavaScript utilisée pour interroger une API.
*
* @license https://ouvert.canada.ca/fr/licence-du-gouvernement-ouvert-canada
*/
(function( $ ) {
$(document).ready(function() {
// Méthode abrégée
$.getJSON('http://www.earthquakescanada.nrcan.gc.ca/api/earthquakes/',
function(json) {
$('#short').append(json.metadata.request.name.en + '<br />');
$.each(json.latest, function(idx, item) {
$('#short').append(idx + ' -> ' + item + '<br />');
});
return;
}
);
// Méthode étendue
$.ajax({
url: 'http://www.earthquakescanada.nrcan.gc.ca/api/earthquakes/',
dataType: 'json',
headers: {
'Accept' : 'application/json',
'Accept-Language' : 'fr'
},
crossDomain: true,
type: 'GET',
success: function(json) {
$('#long').append(json.metadata.request.name.fr + '<br />');
$.each(json.latest, function(idx, item) {
$('#long').append(idx + ' -> ' + item + '<br />');
});
return;
},
error: function(req, status, error) {
$('#long').append(
status.toString() + ': ' +
error.toString()
);
return;
},
});
});
})( jQuery );
</script>
</body>
</html>
Sortie :
Earthquake listings available 7d -> /api/v2/locations/latest/7d.json 30d -> /api/v2/locations/latest/30d.json 365d -> /api/v2/locations/latest/365d.json --- Annonces de séismes disponibles 7d -> /api/v2/locations/latest/7d.json 30d -> /api/v2/locations/latest/30d.json 365d -> /api/v2/locations/latest/365d.json
Java
Plusieurs bibliothèques de tiers pour Java SE facilitent le travail avec les données JSON. Dans l'exemple qui suit, nous utilisons la bibliothèque JSON.org (anglais seulement), également accessible par l'entremise de Maven (anglais seulement).
package com.tbs.devcorner.simple;
/**
* Exemple simple de programme Java utilisé pour interroger une API.
* @license https://ouvert.canada.ca/fr/licence-du-gouvernement-ouvert-canada
*
* Énoncé Dependency de Maven :
* <dependency>
* <groupId>org.json</groupId>
* <artifactId>json</artifactId>
* <version>20131018</version>
* </dependency>
*/
import java.io.*;
import java.net.*;
import org.json.*;
public class App
{
public static void main( String[] args )
{
try {
// Créer la connexion
URL api_url = new URL("http://www.earthquakescanada.nrcan.gc.ca/api/earthquakes/");
URLConnection api = api_url.openConnection();
// Définir les en-têtes HTTP
api.setRequestProperty("Accept", "application/json");
api.setRequestProperty("Accept-Language", "en");
// Obtenir la réponse
JSONTokener tokener = new JSONTokener(api.getInputStream());
JSONObject jsondata = new JSONObject(tokener);
// Afficher le nom de l'API
System.out.println(jsondata.getJSONObject("metadata")
.getJSONObject("request")
.getJSONObject("name")
.get("en").toString());
// Répéter l'opération sur les liens les plus récents
JSONObject latest = jsondata.getJSONObject("latest");
for (Object item : latest.keySet()) {
System.out.println(item.toString() + " -> " + latest.get(item.toString()));
}
} catch (MalformedURLException e) {
System.out.println("URL mal formée");
} catch (IOException e) {
System.out.println("Erreur d'E/S");
}
}
}
Output:
Earthquake listings available 7d -> /api/v2/locations/7d.json 30d -> /api/v2/locations/30d.json 365d -> /api/v2/locations/365d.json