Géocodage par lots

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

Il y a trois façons de géocoder plusieurs adresses, et seules les deux premières sont des surfaces d'API.

POST /geocode/batch est l'API : jusqu'à 100 recherches, une requête HTTP, un appel facturé par requête non vide. Il y a un exemple à copier.

unmap geocode csv est un client de cette même route pour un fichier sur votre machine. Le fichier ne quitte jamais votre machine; seule la colonne choisie est envoyée.

Le lot hébergé est la troisième, et c'est une fonction du tableau de bord plutôt qu'une API : vous téléversez un CSV sur unmap.dev/dashboard/batch, unmap le conserve pendant le traitement et pendant une durée de rétention publiée, et vous téléchargez la copie annotée. Il s'authentifie par session de navigateur : une clé API ne peut pas l'atteindre, et il n'y a ni SDK ni CLI pour lui. Voir Lot hébergé plus bas.

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}'

import { Geocoder } from "@unmap/geocoding";
 
const geocoder = new Geocoder({ key: "um_live_..." });
const results = await geocoder.batch(["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.

Colonne	Signification
`unmap_status`	`matched`, `review`, `no_match`, `invalid`, `failed` ou `unprocessed`
`unmap_id`	Identifiant stable de la fiche appariée
`unmap_name`	Le libellé résolu par le géocodeur
`unmap_lng`, `unmap_lat`	Coordonnées, WGS84
`unmap_layer`	`address`, `street`, `locality`, `region` ou `poi`
`unmap_source`	Le jeu de données d'où provient la fiche
`unmap_match_type`	`exact`, `partial`, `fallback` ou `unknown`
`unmap_precision`	`point`, `street`, `locality`, `region` ou `unknown`
`unmap_review`	Pourquoi 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

Option	Défaut	Ce qu'elle borne
`--rate`	10 par seconde	La vitesse d'envoi, en moyenne
`--concurrency`	4	Le nombre de requêtes en vol à la fois
`--max-attempts`	4	Les 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.

`POST /geocode/batch` n'est pas une API de traitements

POST /geocode/batch répond dans le même appel HTTP. Elle retourne des résultats, pas un identifiant de traitement; unmap ne conserve rien pour elle, ne la met pas en file, et n'accepte pas de webhook. Tout ce qui précède ce titre décrit cette requête.

Lot hébergé, dans le tableau de bord

Il existe un exécuteur de traitements asynchrones, et c'est le seul endroit de la plateforme où unmap stocke un fichier client. Ce n'est pas une API : il s'authentifie par votre session de navigateur, donc une clé API ne peut pas l'atteindre, et il n'y a ni méthode SDK ni commande CLI pour lui.

Utilisez-le depuis unmap.dev/dashboard/batch. Le déroulé est : téléverser, choisir la colonne d'adresse, lire l'estimation, puis Démarrer le géocodage. Rien n'est facturé avant ce bouton.


Forfaits	Forfaits payants seulement. Le forfait gratuit sert au développement.
Taille	10 000 lignes / 25 Mio par fichier sur indie; 100 000 lignes / 50 Mio sur growth.
Simultanéité	Un traitement en cours sur indie, deux sur growth.
Facturation	Un appel par ligne admissible, sur l'allocation partagée avec les cartes et l'itinéraire. Une ligne qui a une valeur dans la colonne d'adresse coûte un appel même sans correspondance; une ligne sans valeur ne coûte rien. Les reprises de la plateforme n'ajoutent jamais de frais.
Progression	Le traitement continue après la fermeture de la page.
Annuler et reprendre	Les deux. Un traitement arrêté par un plafond de dépenses reprend une fois le plafond relevé.
Échec partiel	Un traitement terminé avec des lignes à revoir le dit, et le téléchargement les sépare.

Rétention. unmap conserve le fichier téléversé, ses fragments analysés, les résultats et les exports pendant sept jours à compter de la création du traitement, puis les supprime. L'horodatage exact est affiché avant le téléversement et sur le traitement lui-même; il n'est pas prolongé par une reprise. Le statut et les compteurs, sans contenu, sont conservés trente jours. La politique de confidentialité indique la même fenêtre. Téléchargez votre copie plutôt que de traiter celle hébergée comme un stockage. unmap ne revendique pas de résidence des données au Canada sur un forfait libre-service, et le lot hébergé n'y change rien : voir Confidentialité pour l'endroit où se fait le traitement.

Une API générique de traitements reste un travail ultérieur

Le lot hébergé est une fonction du géocodage par lots, pas une API de traitements de plateforme. Une API générique est un travail ultérieur, et elle sera asynchrone de la même façon : POST /jobs retourne 202 et un identifiant, le client interroge GET /jobs/:id, et 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 plutôt qu'une extension du CSV hébergé, et elle s'authentifiera par clé. 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

L'API de géocodage pour la recherche que ceci regroupe, une requête à la fois.
Géocoder plusieurs adresses reprend la requête comme exemple à copier.
Forfaits et limites pour ce qu'un gros lot coûte sur votre quota.
Confidentialité pour la durée de conservation d'un fichier de lot hébergé.