EN
Aller au contenu

Géocodage par lots

Chaque requête nécessite une clé API; voir Authentification.

Le produit est POST /geocode/batch : jusqu'à 100 recherches, une requête HTTP, un appel facturé par requête non vide. Il y a un exemple à copier. Un CSV est un fichier sur votre machine. unmap geocode csv est un client de cette route. unmap ne stocke pas le fichier.

L'API

POST /geocode/batch

Le corps est du JSON. queries est obligatoire : 1 à 100 chaînes, ordre conservé. Contrôles de recherche partagés seulement (lang, limit, layers, focus, region, bbox). La réponse est un tableau aligné sur queries. L'index i est ce que GET /geocode/search retournerait pour cette chaîne. Les entrées vides restent [] et ne sont pas facturées. Plus de 100 requêtes donne un 413. Une allocation restante inférieure au nombre de requêtes non vides refuse la requête entière.

curl -X POST "https://api.unmap.dev/geocode/batch" \
  -H "Authorization: Bearer $UNMAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queries":["17 Ave SW Calgary","Springfield"],"limit":1}'

geocoder.batch découpe une liste plus longue par 100. Un fichier de 100 000 lignes, c'est 1 000 requêtes cliente, pas une file d'attente Worker. L'API de géocodage porte le contrat complet.

Un CSV sur votre machine

unmap geocode csv lit le fichier, envoie la colonne désignée par lots de 100, et écrit une copie avec dix colonnes ajoutées. Votre fichier n'est jamais modifié et jamais téléversé.

npx @unmap/cli geocode csv adresses.csv --query-column address --output geocode.csv --review-output revision.csv

Téléchargez un fichier d'exemple pour l'essayer. Vingt lignes synthétiques couvrant les cas qui valent la peine d'être vus : accents, une rue sans numéro civique, une route rurale, le même nom de rue dans deux provinces, une ligne vide et une adresse impossible à résoudre.

Seule la colonne que vous désignez quitte la machine. Les colonnes non désignées ne sont jamais envoyées. Votre clé d'API provient de --key, de la variable d'environnement UNMAP_KEY ou de unmap.config.json. Elle n'est jamais écrite dans la sortie, le fichier de révision, le fichier de reprise, ni dans aucun message affiché par l'outil.

Compter avant de dépenser

--estimate valide la correspondance de colonne et compte les lignes sans envoyer une seule requête.

npx @unmap/cli geocode csv adresses.csv --query-column address --estimate
20 rows, 19 with an address, 1 without.
1 requests if nothing retries; up to 4 if every request uses all 4 attempts.
Each request geocodes up to 100 addresses. Every successful address is one billed call. Retries are billed.
Remaining allowance: unknown from the CLI. Check the dashboard at unmap.dev/dashboard/usage.

La sortie de l'outil en ligne de commande est en anglais. Deux nombres, pas un seul. Les requêtes sont des POST d'au plus 100 adresses. Chaque adresse réussie est un appel sur votre forfait. Une requête réessayée est facturée à nouveau, comme pour GET /geocode/search. Une ligne sans adresse en coûte zéro. L'estimation donne le plancher et le plafond, et dit lequel est lequel.

--sample 100 ne traite que les cent premières lignes ayant une adresse, puis s'arrête et enregistre un point de reprise. Cela envoie bel et bien des requêtes, et elles sont facturées. Relancez avec --resume et sans --sample pour terminer.

Les colonnes ajoutées

Dix colonnes, toutes préfixées unmap_, ajoutées après les vôtres. Si votre fichier porte déjà l'un de ces noms, la colonne ajoutée est suffixée (unmap_status_2) au lieu d'écraser la vôtre, et l'outil vous le dit.

ColonneSignification
unmap_statusmatched, review, no_match, invalid, failed ou unprocessed
unmap_idIdentifiant stable de la fiche appariée
unmap_nameLe libellé résolu par le géocodeur
unmap_lng, unmap_latCoordonnées, WGS84
unmap_layeraddress, street, locality, region ou poi
unmap_sourceLe jeu de données d'où provient la fiche
unmap_match_typeexact, partial, fallback ou unknown
unmap_precisionpoint, street, locality, region ou unknown
unmap_reviewPourquoi la ligne mérite un coup d'oeil, le cas échéant

unmap_status et unmap_match_type répondent à deux questions différentes, et la combinaison à surveiller est matched avec fallback. Elle signifie qu'une réponse est revenue et qu'elle est plus grossière que la demande : vous avez donné un numéro civique et obtenu la rue. Voir métadonnées de résultat.

Le fichier de révision

--review-output écrit un second CSV qui ne contient que les lignes méritant un coup d'oeil : réponses plus grossières que la demande, concordances partielles, quasi-égalités entre les deux meilleurs candidats, lignes sans résultat et lignes en échec. C'est un sous-ensemble de la sortie principale, au même format et avec les mêmes colonnes.

Chaque ligne d'entrée figure exactement une fois dans la sortie principale, quoi qu'il lui soit arrivé. Rien n'est écarté en silence, et c'est tout l'intérêt d'avoir une colonne de statut.

Interrompre

Ctrl-C arrête l'exécution après les requêtes déjà en vol, puis écrit un fichier de reprise à côté de la sortie. Relancez la même commande avec --resume et elle repart de la dernière ligne écrite de façon durable.

npx @unmap/cli geocode csv adresses.csv --query-column address --output geocode.csv --resume

La reprise est refusée si le fichier d'entrée ou la correspondance de colonne a changé : les numéros de ligne ne concorderaient plus et la moitié du fichier aurait été géocodée autrement. Changer le rythme (--rate, --concurrency, --max-attempts) est permis : cela change l'effort de l'outil, pas ce à quoi une ligne se résout.

Une chose que la reprise ne peut pas faire : une requête en vol au moment de l'arrêt a peut-être déjà été servie, et elle sera renvoyée. Rien sur votre machine ne peut savoir lesquelles, donc une reprise peut facturer deux fois un petit nombre de lignes.

Rythme

OptionDéfautCe qu'elle borne
--rate10 par secondeLa vitesse d'envoi, en moyenne
--concurrency4Le nombre de requêtes en vol à la fois
--max-attempts4Les tentatives par requête, la première comprise

Le débit et la concurrence bornent deux choses différentes et se règlent séparément. Les valeurs par défaut restent délibérément bien en deçà de la limite de rafale par clé, parce qu'un travail par lots partage l'allocation de votre compte avec ce que vous servez à de vrais utilisateurs. Voir forfaits et limites.

Les nouvelles tentatives ne visent que les échecs qui pourraient réussir plus tard : une limite de débit, un délai dépassé, une erreur 5xx. Une requête mal formée n'est jamais réessayée. Une clé invalide arrête immédiatement toute l'exécution sans marquer aucune adresse comme mauvaise, parce que l'adresse n'était pas le problème. Un quota épuisé ou un plafond de dépenses atteint arrête aussi l'exécution au lieu d'insister; relancez avec --resume une fois la limite levée.

Tableurs

--spreadsheet-safe préfixe une tabulation à toute valeur qu'Excel, Sheets ou LibreOffice évaluerait comme une formule, afin qu'une cellule commençant par =, +, - ou @ s'affiche comme du texte. L'option est désactivée par défaut parce qu'elle modifie les octets, et qu'un traitement automatisé qui relit le fichier veut la valeur d'origine.

Ce que l'outil ne fait pas

  • Il géocode du texte libre. La correspondance de colonnes séparées pour l'adresse, la ville et la province passe par la recherche structurée et n'est pas encore branchée dans la ligne de commande.
  • Il ne valide pas la distribution du courrier. Un code postal dans une ligne est comparé à celui que porte la fiche appariée; unmap ne sait pas si une adresse reçoit du courrier.
  • Canada seulement.

Pas une API de traitements

Il n'y a pas de POST /jobs aujourd'hui, et POST /geocode/batch n'en est pas une. La requête répond dans le même appel HTTP. unmap ne conserve pas votre fichier, ne maintient pas une file après la fermeture de l'onglet, et n'accepte pas de webhook.

Une API générique de traitements est un travail ultérieur, et elle sera asynchrone : POST /jobs retourne 202 et un identifiant; le client interroge GET /jobs/:id et lit le résultat seulement quand le traitement a réussi. La requête de création n'attend pas le travail. Le déclencheur est le premier produit qui ne peut pas finir en une requête : une grande matrice d'itinéraires, beaucoup de trajets camion, tout ce qui dépasse le budget d'un Worker ou d'un conteneur. Cette API sera un nouveau préfixe et de nouvelles tables, pas une extension du CSV hébergé. Le géocodage n'y aura pas de gestionnaire dans cette première coupe. Ne la construisez pas pour accélérer un tableur.

Prochaines étapes