API Import

Sommaire

Introduction

L’API d’import est utilisée sur notre application web pour importer des fichiers d’adresses. Les formats tableurs sont autorisés comme le .xls, .xlsx et .ods. Les formats textuels .csv et .txt sont autorisés également, et dans ce cas il est préférable d’utiliser l’encodage de caractères UTF-8. Voir plus d’informations sur les formats supportés ici.

Cette API REST utilise le protocole HTTP/1.1 avec SSL et nécessite  une requête de type POST pour fonctionner. On peut constituer de telles requêtes HTTP POST avec Javascript et jQuery dans un navigateur, ou bien avec le logiciel cURL en CLI sous Linux ou Windows, ou encore la librairie cURL pour PHP ou cURL pour C/C++.

Paramètres GET et POST de cette API

Liste des paramètres de cette API

L’interrogation de l’API se fait avec un paramètres GET (key) et quatre paramètres POST. Pour rappel sur HTTP, un paramètre GET est visible dans l’URL (après le signe ? ou les signes &) tandis qu’un paramètre POST n’est pas visible dans l’URL mais seulement le corps de la requête HTTP.

Paramètre Explication Méthode
key Clé API sur 32 caractères. GET
js_finfo[name] Nom du fichier. POST
js_finfo[lastModified] Date de modification du fichier au format EPOCH, nombre de secondes depuis le 01/01/1970 00:00:00. POST
js_finfo[size] Taille du fichier en octets. POST
js_finfo[type] Type MIME du fichier (exemple : text/plain). POST
file Contenu du fichier encodé en chaine base64. POST

L’adresse URL à interroger en HTTP POST est : https://maps.open-street.com/api/import/?key=ma-cle . Il faudra remplacer « ma-cle » par votre clé API que vous pouvez trouver dans votre espace client onglet « Comptes de calcul ».

Requête avec Javascript sur une page web

Si vous utiliser cette API d’Import sur une appli web, les informations du tableau js_finfo peuvent facilement être obtenues en Javascript. Si vous utiliser un champ d’upload de type <input id="fld-files" type="file"> alors il vous suffira de renseigner le tableau js_finfo comme ceci (avec jQuery).

L’envoi de la requête peut être fait par jQuery.post() ou encore XMLHttpRequest comme par exemple le code suivant. Le Content-type doit être x-www-form-urlencoded. Ici le contenu est ĥardcodé avec la variable file  qui vaut le code base64 : dG90bw== et la variable js_finfo[name]  qui vaut data001.js .

Vous pouvez regarder la méthode d’interrogation de cette API sur notre application web grâce aux outils pour les développeurs de votre navigateur Firefox ou Chrome.

Requête POST d'import de fichier

Requête POST d’import de fichier

Requête avec cURL en ligne de commande Linux

Voici ci-dessous un script nommé envoi.sh qui permet d’envoyer le fichier dont le chemin sera soumis en premier argument. Ce fichier sera encodé en base64 puis passé à cURL via l’entrée standard stdin. Regarder la manpage curl pour plus d’informations sur cette méthode file@-.

Le Content-Type n’est pas configuré mais curl le renseigne avec une valeur par défaut qui doit probablement être x-www-form-urlencoded.

Contenu du fichier contenu.txt à envoyer :

Commande d’envoi et de visualisation du retour :

Retour JSON

Cette API renvoie une sortie JSON avec des informations sur le fichier, et un tableau qui comporte le fichier parsé sous forme de tableau. Cela est utile pour exploiter avec Javascript des données qui provenaient à l’origine d’un classeur .xlsx.

On remarque les valeurs suivantes :

  • php_finfo[type] est le type de fichier retourné par finfo::buffer() (PHP).
  • php_finfo[type_mine] est le type MIME du fichier retourné par finfo::buffer() avec la constante FILEINFO_MIME_TYPE (PHP).
  • php_finfo[extension] est l’extension après le point.
  • php_finfo[CRLF] donne des indications sur le fichier texte, si le fichier envoyé est un fichier texte.
    • CR : sauts de lignes de type CR ou \r (carriage return)
    • LF : sauts de lignes de type LF ou \n (line feed)
    • CRLF : sauts de lignes de type CRLF ou \r\n
    • LL : lignes très longes
    • BOM : avec indicateur d’ordre des octets BOM (byte order mark)
    • BE : Big Endian
    • LE : Long Endian
  • php_finfo[encoding] donne l’encodage de caractères du fichier texte, si le fichier envoyé est un fichier texte.
  • md5 : hash md5 du contenu du fichier
  • parse : tableau des données du fichier d’entrée (.txt, .csv, .xls, .xlsx, .ods) utilisable avec un langage de programmation.