Géocodage par lots

Vous avez un tableur d'adresses et vous voulez des coordonnées à côté. unmap geocode csv lit le fichier, envoie une colonne à l'API de géocodage et écrit une copie avec dix colonnes ajoutées. Votre fichier n'est jamais modifié.

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.

Dans le tableau de bord

Si vous préférez ne pas l'exécuter localement, le géocodage par lots du tableau de bord fait le même travail de notre côté : téléversez, choisissez la colonne, regardez ce que cela coûtera, lancez. Le traitement continue après la fermeture de l'onglet.

Les deux produisent le même fichier, avec les mêmes colonnes dans le même ordre : vous pouvez prototyper avec la ligne de commande et déplacer le traitement vers le tableau de bord sans que rien en aval ne s'en aperçoive.

Trois différences à connaître :

• Un forfait payant est requis. Le forfait gratuit couvre le développement sur localhost; traiter un fichier de production sur nos machines est du travail payant.
• Les nouvelles tentatives ne vous coûtent rien. Le service hébergé facture un appel par ligne admissible qui obtient une réponse, quel que soit le nombre d'essais. La ligne de commande réessaie en HTTP, donc chaque tentative y est facturée : c'est pourquoi --estimate annonce un plafond et le tableau de bord non.
• Votre fichier est conservé pendant le traitement. Il est supprimé sept jours après le téléversement, et la date exacte est affichée avant le téléversement et sur la page du traitement. La ligne de commande, elle, n'envoie jamais le fichier.

Limites par traitement, selon le forfait :

Ces limites bornent le coût d'hébergement du travail, pas ce que vous avez le droit de dépenser. Les lignes sont facturées comme des appels ordinaires sur la même allocation mensuelle que vos cartes et vos itinéraires.

Ce qui quitte votre machine

Uniquement la colonne que vous désignez. Le fichier reste où il est, les colonnes non désignées ne sont jamais envoyées, et la sortie ainsi que le fichier de reprise sont écrits à côté de votre entrée sans jamais être téléversés nulle part.

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.

--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.
19 requests if nothing retries; up to 76 if every row uses all 4 attempts.
One request is one API call against your plan's shared allowance. 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, parce qu'une ligne d'entrée n'est pas une requête facturée. Une ligne qui échoue temporairement puis réussit au troisième essai compte pour trois appels. 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.

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.

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

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.