API de géocodage

Le géocodage transforme du texte en coordonnée, et inversement. Quatre points de terminaison le font sur environ 19 millions d'adresses et lieux canadiens : la recherche à partir d'une requête complète, la saisie semi-automatique à partir d'une requête partielle, la recherche par catégorie autour d'un point, et la recherche inverse d'une coordonnée vers le lieu le plus proche. Une cinquième route, POST /geocode/batch, lance jusqu'à 100 recherches en une requête.

La recherche et la saisie semi-automatique sont classées par pertinence plutôt que par correspondance de sous-chaîne, de sorte que « 17 Ave SW Calgary » trouve l'avenue et non chaque fiche contenant le mot Calgary. Les points de terminaison « nearby » et « reverse » sont plutôt triés par distance réelle. Chaque fiche porte ses noms bilingues, ainsi que les noms en langues autochtones lorsque la source les fournit.

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

Voici une recherche en direct, et les deux lignes qui l'ont produite :

import { Unmap } from "@unmap/sdk";

const unmap = new Unmap({ key: "um_live_..." });

const results = await unmap.geocoder.search("Calgary Tower", { limit: 3 });

npm i @unmap/geocoding

pnpm add @unmap/geocoding

yarn add @unmap/geocoding

bun add @unmap/geocoding

@unmap/geocoding est le client autonome (sans dépendance à la carte); @unmap/sdk expose le même objet sous unmap.geocoder. Tout ce qui suit est le contrat HTTP sous les deux.

Les quatre points de terminaison à requête unique retournent un tableau JSON, même pour zéro ou un seul résultat. Le lot retourne un tableau de ces tableaux, un emplacement par requête :

[
  {
    "id": "23493650",
    "name": "Calgary",
    "layer": "locality",
    "lng": -114.08529,
    "lat": 51.05011,
    "score": 11.18,
    "source": "nrcan_cgndb",
    "match_type": "exact",
    "precision": "locality",
    "names": { "en": "Calgary" },
    "address": { "city": "Calgary", "region": "AB", "country": "CA" }
  }
]

• id : identifiant stable. Toujours une chaîne, même si la valeur sous-jacente est numérique.
• name : libellé à afficher. Il est résolu dans cet ordre : l'entrée de names correspondant au lang demandé, puis le nom français de la fiche si vous avez demandé fr, puis le nom par défaut, puis names.en, puis n'importe quelle autre valeur de names. Une fiche d'adresse ordinaire n'a aucun de ces noms; son libellé est alors composé à partir de ses parties : 101 17 Avenue SW, Calgary. Seule une fiche sans nom ni rue, que le corpus ne devrait pas contenir, retourne une chaîne vide.
• layer : le type de résultat, soit address, street, locality (une ville ou un village), region (une province ou un territoire), poi (un point d'intérêt comme un commerce ou un parc), legal_land (une description d'arpentage), well, facility ou parcel. Les résultats civiques restent inchangés.
• lng, lat : la position, en degrés de longitude et de latitude, les mêmes nombres que ceux fournis par l'API de géolocalisation du navigateur.
• score : score de classement, présent uniquement pour la recherche et la saisie semi-automatique. Plus il est élevé, plus le résultat est pertinent. Il n'est pas comparable d'une requête à l'autre.
• distance : distance en mètres depuis le point autour duquel vous avez cherché, mesurée sur la courbure de la Terre et arrondie au mètre. Présente uniquement sur les résultats de nearby. Plus la valeur est basse, plus le résultat est proche, et les résultats arrivent déjà dans cet ordre.
• category : identifiant canonique de la taxonomie porté par la fiche, par exemple health.pharmacy. Présent sur les résultats de nearby. Les autres points de terminaison ne le retournent pas.
• names : table des libellés par langue (en, fr, iu, cr, etc.), présente dès qu'il en existe au moins un; l'exemple « Calgary » ci-dessus n'en porte qu'un. Toutes les clés ne sont pas des langues : une fiche peut aussi porter des graphies alternatives que les gens tapent, soit en-alt1 … en-alt3 et fr-alt1 … fr-alt3 (noms usuels ou variantes, par exemple Old Montreal pour Vieux-Montréal) et, pour les aéroports, en-iata (YYZ) et en-iata2 (YYZ Airport). La recherche les reconnaît et les traite comme des correspondances exactes, mais elles ne servent jamais de name. Si vous parcourez names pour construire un sélecteur de langue, ignorez les clés qui se terminent par -alt ou -iata, suivi ou non d'un chiffre. Omise seulement lorsque la fiche n'a aucun libellé.
• source, source_id : le jeu de données d'où provient la fiche retournée, et son identifiant dans ce jeu. Les fiches qui décrivent le même lieu sont fusionnées avant l'indexation et une seule survit : c'est donc la source de la survivante, et non la liste de tout ce qui concordait. Voir Couverture.
• match_type, precision, match_reasons : dans quelle mesure le résultat répond à votre demande, et avec quelle précision il est positionné. Voir Métadonnées de résultat plus bas.
• address : composants d'adresse (numéro, unité, rue, ville, région, code postal, pays), présents lorsqu'au moins un existe pour la fiche. Omis sinon. unit n'apparaît que lorsqu'une source l'a publié, ce qui est rare.
• legal_land : présent sur un résultat de terre légale. { system, province?, canonical, unit, components }.
• uwi, licence, operator, status : présents sur un puits ou une installation.
• pid : PID ParcelMap BC sur un résultat parcel.
• bbox : emprise de la cellule [minLng, minLat, maxLng, maxLat] lorsque la fiche a une géométrie.
• geometry : le polygone d'arpentage, seulement si vous passez geometry=true et que la fiche en a un.

GET /geocode/search

• q (obligatoire) : texte de recherche.
• lang (facultatif, en par défaut) : langue du champ name.
• limit (facultatif, 10 par défaut, limité à 1-50). Une valeur non numérique retombe sur la valeur par défaut au lieu de faire échouer la requête.
• bbox (facultatif) : minlon,minlat,maxlon,maxlat. C'est un filtre strict, pas une simple pondération. Une fiche située hors du rectangle est écartée des résultats, donc un rectangle vide retourne [].

curl "https://api.unmap.dev/geocode/search?q=Calgary%20Tower&limit=3" \
  -H "Authorization: Bearer $UNMAP_API_KEY"

import { Geocoder } from "@unmap/geocoding";
 
const geocoder = new Geocoder({ key: "um_live_..." });
const results = await geocoder.search("Calgary Tower", { limit: 3 });

Un q absent donne un 400 : { "error": "q required" }. Un bbox mal formé (autre chose que quatre nombres finis) donne un 400 : { "error": "bbox must be minlon,minlat,maxlon,maxlat with 4 finite numbers" }.

Nommer une ville dans le texte de la requête pondère les résultats en sa faveur sans les y contraindre. 17 Ave SW Calgary résout bien sur la 17e Avenue SO à Calgary, et une correspondance légitime juste à l'extérieur des limites municipales est encore retournée, simplement plus bas. Utilisez bbox lorsque vous voulez une frontière stricte.

Contrôles de recherche

Trois paramètres optionnels, communs à la recherche, à la saisie semi-automatique et à la recherche structurée. Deux d'entre eux excluent des résultats, le troisième ne fait que les réordonner, et c'est toute la distinction :

• layers : les types de résultats admis, parmi address, street, locality, region, poi. Filtre strict. Une valeur inconnue donne un 400 au lieu d'être ignorée : une faute de frappe vous le dit plutôt que de chercher silencieusement dans tout le corpus. Les valeurs énergie well et facility sélectionnent plutôt le corpus énergie et exigent ce module complémentaire; les deux ensembles ne se mélangent pas.
• region : une province ou un territoire, dans n'importe quelle graphie (AB, Alberta, alta., Québec). Filtre strict avec une seule règle : il exclut les fiches qui le contredisent et conserve celles qui n'en disent rien. Une fiche de rue sans province reste admise et signale region_not_verified. Nommer une province dans q ne fait qu'orienter le classement; ce paramètre, lui, exclut.
• focus : lng,lat. Préférence souple. Elle rapproche le classement du point sur environ 25 km et n'exclut rien : un résultat pertinent à l'autre bout du pays revient quand même, derrière les proches. C'est la différence avec bbox : « privilégier les environs » n'est pas « se limiter à cette zone ».

Les filtres stricts se composent par intersection, et des filtres contradictoires ne retournent aucun résultat plutôt que d'élargir la recherche en silence. focus ne s'applique qu'à ce qui survit aux filtres.

curl "https://api.unmap.dev/geocode/search?q=Springfield&layers=locality&focus=-63.57,44.64" \
  -H "Authorization: Bearer $UNMAP_API_KEY"

GET /geocode/structured

Quand vous savez déjà quelle partie est la rue et laquelle est la province, dites-le. Un moteur plein texte doit deviner, et une province mal devinée devient un mot de recherche ordinaire, libre de faire remonter n'importe quelle fiche.

• address (optionnel) : la ligne de rue, numéro civique et nom de rue.
• city (optionnel)
• region (optionnel) : n'importe quelle graphie acceptée, normalisée en code à deux lettres.
• postalcode (optionnel) : avec ou sans l'espace.
• country (optionnel) : CA uniquement.

Au moins un de address, city ou postalcode est requis. Une province seule donne un 400 : ce n'est pas une recherche, c'est une demande de quatre millions de fiches.

Chaque champ a un rôle et un seul. address et city déterminent quelles fiches sont candidates et laquelle gagne. region et postalcode restreignent, selon la règle ci-dessus : ils excluent les fiches qui les contredisent et conservent celles qui n'en disent rien. country est validé, pas apparié.

curl "https://api.unmap.dev/geocode/structured?address=100%20Main%20Street&city=London&region=ON" \
  -H "Authorization: Bearer $UNMAP_API_KEY"

import { Geocoder } from "@unmap/geocoding";
 
const geocoder = new Geocoder({ key: "um_live_..." });
const results = await geocoder.structured({
  address: "100 Main Street",
  city: "London",
  region: "ON",
});

Les grammaires de terre légale, de parcelle et d'énergie ne sont pas détectées ici : ce sont des formes de chaîne plein texte, et une rue qui s'appelle littéralement NW-25-24-1-W5 reste une rue.

Métadonnées de résultat

Chaque résultat indique d'où il vient et dans quelle mesure il répond à votre demande. Ce sont deux questions distinctes, et les champs les gardent distinctes.

match_type porte sur ce que vous avez saisi :

La règle que cela sert à garantir : une rue ou une ville qui tient lieu d'adresse est toujours fallback, jamais exact. Demander 101 17 Ave SW Calgary et obtenir l'avenue est une réponse utile, et une réponse trompeuse si rien ne la distingue du bâtiment.

precision porte sur la position : point, street, locality, region ou unknown. point signifie une fiche ponctuelle distincte dans la source, un point d'adresse ou un point d'intérêt. Ce n'est pas une affirmation de précision au toit, et cela ne veut jamais dire interpolé, puisque rien n'est interpolé. locality et region sont des centroïdes.

Les deux axes sont indépendants. Chercher « Toronto » et obtenir la ville donne exact et locality en même temps : une concordance parfaite, à la précision d'une ville.

match_reasons explique une concordance non exacte au moyen de codes stables, et est absent lorsque la concordance est exacte : housenumber_not_matched, housenumber_differs, unit_not_verified, unit_differs, postalcode_not_verified, postalcode_differs, region_not_verified, region_differs, terms_unmatched, fuzzy_match.

score est inchangé et reste un score de pertinence brut. Aucun de ces champs n'est un indice de confiance, et aucun n'est dérivé de score.

GET /geocode/autocomplete

Mêmes paramètres q, lang et limit que la recherche, avec limit=8 par défaut. L'endpoint est conçu pour les frappes successives plutôt que pour une requête unique et délibérée. Il reconnaît de vrais préfixes partiels et pas seulement des mots indexés complets : Calgar trouve Calgary, Vancou trouve Vancouver. Ce point de terminaison n'accepte pas de bbox.

curl "https://api.unmap.dev/geocode/autocomplete?q=rue+sainte-cath&lang=fr&limit=5" \
  -H "Authorization: Bearer $UNMAP_API_KEY"

const hints = await geocoder.autocomplete("rue sainte-cath", { lang: "fr", limit: 5 });

import { Unmap } from "@unmap/sdk";

const unmap = new Unmap({ key: "um_live_..." });

const results = await unmap.geocoder.autocomplete("rue sainte-cath", { limit: 5, lang: "fr" });

Envoyez tout le contenu du champ, pas seulement le dernier mot. Chaque mot sauf le dernier doit correspondre à un jeton en entier, et le dernier est traité comme le préfixe en cours de frappe : Calgary Tow trouve Calgary Tower et rue sainte-cath trouve rue Sainte-Catherine. L'ordre des mots n'a pas d'importance, les traits d'union sont des limites de mots, et les accents sont repliés comme l'index les replie, donc cathé et cathe sont le même préfixe. Une saisie sans aucune lettre ni chiffre retourne [].

Un q absent donne le même 400 : { "error": "q required" }.

Une chose à savoir avant de brancher cet endpoint sur un champ de saisie : le classement y est plus grossier que celui de la recherche. Il repose sur la correspondance des termes, la prominence de la fiche et la même pondération par couche que la recherche, et sur rien d'autre : pas de bonus de nom exact, pas de pondération vers un lieu nommé ailleurs dans la requête, pas de seconde passe tolérante aux fautes de frappe. Une saisie de trois caractères ou moins est traitée comme une requête de lieu et ne retourne que des localités, des provinces et des points d'intérêt; les adresses et les rues reviennent au quatrième caractère. Utilisez /geocode/search quand vous voulez la meilleure réponse unique, et la saisie semi-automatique quand vous voulez des suggestions rapides.

GET /geocode/nearby

Recherche par catégorie : les lieux d'un type donné autour d'un point, triés par distance. C'est un point de terminaison distinct de la recherche, volontairement. Le texte libre n'est jamais interprété comme une catégorie, donc demander des banques ici ne peut pas retourner une rue nommée Silverado Bank Circle.

• category (obligatoire) : de une à huit catégories, séparées par des virgules. Chaque jeton est soit un identifiant canonique de la taxonomie (health.pharmacy), soit un mot courant en anglais ou en français (pharmacy, pharmacie). La correspondance ignore la casse, les accents et les traits d'union : Épicerie, epicerie et EPICERIE résolvent tous vers shop.supermarket. La résolution se fait dans l'API et non dans une bibliothèque cliente, donc les alias fonctionnent depuis un simple curl.
• near (lng,lat) ou bbox (minlon,minlat,maxlon,maxlat) : exactement un des deux est obligatoire. Fournir les deux, ou aucun, donne un 400. Un bbox ancre la recherche au centre du rectangle et en déduit un rayon qui le couvre : c'est une façon de dire « par ici », pas un rectangle de découpe. Un résultat peut donc se trouver dans ce rayon et hors des coins du rectangle.
• radius (facultatif) : en mètres, 5000 par défaut, limité à 50-50000. Un radius explicite l'emporte sur celui déduit d'un bbox.
• limit (facultatif, 10 par défaut, limité à 1-50).
• lang (facultatif, en par défaut) : langue du champ name.

Les résultats sont triés du plus proche au plus lointain et portent distance en mètres ainsi que category. Ils ne portent pas de score : le plus proche est le plus proche, et mêler la pertinence à cela, c'est ainsi qu'un grand magasin éloigné passe devant la pharmacie d'en face.

curl "https://api.unmap.dev/geocode/nearby?category=pharmacy&near=-114.07,51.05&limit=3" \
  -H "Authorization: Bearer $UNMAP_API_KEY"
 
# Même requête en français, et deux catégories à la fois
curl "https://api.unmap.dev/geocode/nearby?category=pharmacie,depanneur&near=-114.07,51.05" \
  -H "Authorization: Bearer $UNMAP_API_KEY"

const pharmacies = await geocoder.nearby("pharmacy", { near: [-114.07, 51.05], limit: 3 });
 
// Même requête en français, et deux catégories à la fois
const shops = await geocoder.nearby(["pharmacie", "depanneur"], { near: [-114.07, 51.05] });

Un jeton non reconnu donne un 400 qui nomme le mot saisi : { "error": "unknown category \"warp_drive\"" }. Une category absente donne un 400, tout comme une valeur qui résout vers plus de huit identifiants. Un ancrage absent ou dupliqué donne { "error": "exactly one of near or bbox required" }, et un near mal formé donne { "error": "near must be lng,lat" }.

Un 503 accompagné de { "error": "category search requires a corpus rebuilt with categories" } signifie que le corpus en service est antérieur à l'étiquetage par catégorie. L'erreur est réessayable et disparaît dès que la prochaine version du corpus est mise en service.

import { Unmap } from "@unmap/sdk";

const unmap = new Unmap({ key: "um_live_..." });

const nearby = await unmap.geocoder.nearby("pharmacie", { near: [-114.0719, 51.0447], radius: 2000, limit: 5, lang: "fr" });

Identifiants de catégorie

Quatre-vingt-onze identifiants, groupés par préfixe. Passez l'un d'eux tel quel dans category, ou passez plutôt le mot courant et laissez l'API le résoudre.

GET /geocode/reverse

• lon, lat (obligatoires) : point à chercher.
• lang (facultatif, en par défaut).
• limit (facultatif, 5 par défaut, limité à 1-50).

curl "https://api.unmap.dev/geocode/reverse?lon=-68.517&lat=63.7467" \
  -H "Authorization: Bearer $UNMAP_API_KEY"

const here = await geocoder.reverse(-68.517, 63.7467);

Des valeurs lon/lat non numériques donnent un 400 : { "error": "lon and lat must be numbers" }. Les résultats sont triés par distance géodésique réelle et non par écart de coordonnées brut. Les degrés de longitude rétrécissent vers les pôles, donc un tri naïf placerait un point plein est devant un point plus proche, et cet effet ne fait que croître à mesure qu'on monte vers le nord.

POST /geocode/batch

Jusqu'à 100 recherches directes en une requête. Le corps est du JSON. La réponse est un tableau aligné sur queries : l'index i est exactement ce que GET /geocode/search retournerait pour cette chaîne.

• queries (obligatoire) : un tableau de 1 à 100 chaînes, ordre conservé. Un tableau vide donne un 400. Plus de 100 donne un 413 payload_too_large.
• lang, limit, layers, focus, region, bbox : les mêmes contrôles partagés que la recherche. Pas d'options par élément en v1.
• Les entrées vides ou seulement d'espaces restent en place comme []. Elles n'atteignent pas Postgres et ne sont pas facturées.

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

const results = await geocoder.batch(["17 Ave SW Calgary", "Springfield"], { limit: 1 });

Chaque requête non vide compte pour un incrément geocode, y compris une absence de correspondance valide. Un 400, un 413 ou une panne du conteneur pour la requête entière n'incrémente rien. Si l'allocation mensuelle restante est inférieure au nombre de requêtes non vides, la passerelle refuse la requête entière (429 quota_exceeded, ou spend_cap / billing_required selon le blocage). Un remplissage partiel casserait l'alignement.

Il n'y a pas de cache de périphérie pour le POST par lots. geocoder.batch découpe une liste plus longue par 100 et concatène dans l'ordre d'entrée. Un CSV sur votre machine est un client de cette route; voir Géocodage par lots et l'exemple.

Mise en cache

Une réponse de géocodage réussie est mise en cache à notre périphérie pendant 24 heures. La clé API est retirée avant que la requête ne soit traitée, donc le corps mis en cache ne dépend que des paramètres de la requête et il est partagé entre toutes les clés qui posent la même question. reverse arrondit lon/lat, et nearby arrondit near, à environ un mètre dans la clé de cache, ce qui permet aux recherches voisines de partager une entrée. Les coordonnées exactes que vous envoyez restent celles auxquelles on répond. Sur nearby, un mot de catégorie et son identifiant canonique partagent aussi une seule entrée, puisque les alias sont résolus avant la construction de la clé.

L'en-tête X-Unmap-Cache de la réponse indique HIT ou MISS. Un HIT reste un appel facturable : le cache réduit notre latence, pas votre facture. Les erreurs ne sont jamais mises en cache et portent Cache-Control: no-store.

@unmap/geocoding enveloppe les points de terminaison avec les mêmes paramètres :

import { Geocoder, GeocoderError } from '@unmap/geocoding'
 
const geocoder = new Geocoder({ key: 'um_live_...' })
 
await geocoder.search('Calgary Tower', { limit: 3, lang: 'fr' })
await geocoder.batch(['17 Ave SW Calgary', 'Springfield'], { limit: 1 })
await geocoder.autocomplete('Yellowkni', { limit: 5 })
await geocoder.nearby(['pharmacy', 'convenience store'], {
  near: [-114.07, 51.05],
  radius: 2000,
  limit: 10,
})
await geocoder.reverse(-68.517, 63.7467)

nearby accepte une catégorie unique ou un tableau de catégories, et transmet vos mots tels quels, donc les alias français fonctionnent aussi. search et autocomplete partagent un même type d'options, donc bbox passe la vérification de types sur les deux, mais seule search en tient compte. reverse n'accepte que lang et signal; appelez le point de terminaison directement si vous avez besoin de son limit. Chaque méthode accepte un AbortSignal sous le nom signal. Une réponse non 2xx lève un GeocoderError qui porte le code HTTP dans .status, et le code lisible par machine de la passerelle dans .code lorsque le corps en portait un.

Langues

La table names peut contenir plusieurs libellés par langue; lang= choisit celui qui revient dans name. La même requête retourne la même fiche quelle que soit la langue : vous choisissez la locale au moment de l'affichage plutôt qu'un jeu de données différent à la construction.

• q=Montreal&lang=en → name: "Montreal", names: {"en":"Montreal","fr":"Montréal","iu":"ᒧᕆᐊᓪ"}
• q=Montreal&lang=fr → name: "Montréal", mêmes names
• q=Iqaluit&lang=iu → name: "ᐃᖃᓗᐃᑦ"

La recherche trouve les noms dans la langue où la requête est écrite, y compris en syllabique inuktitut : q=ᐃᖃᓗᐃᑦ résout vers la localité d'Iqaluit et non vers un bâtiment voisin sans rapport. La couverture est une question de sources et non de moteur : le corpus porte un nom inuktitut pour certaines communautés et pas pour d'autres, donc un lieu sans nom iu dans les données sources n'a encore rien à faire correspondre à une requête en syllabique, même si le moteur de recherche gère toutes les langues présentes.

Une requête bien formée du système d'arpentage Dominion (ou SNRC / FPS / concession ontarienne / lots de rivière) sort du classement civique BM25 et retourne layer: "legal_land". Mélanger les deux, c'est ainsi que 25-24-1-W5 devient une rue en Ontario : une analyse réussie ne retombe jamais sur le classement d'adresses.

C'est le complément legal-land. Une clé de compte sans ce complément reçoit un 403 :

{
  "error": "Legal Land requires the Legal Land add-on",
  "code": "addon_required",
  "capability": "legalLand",
  "addon": "addon-legal-land",
  "message": "Legal Land requires the Legal Land add-on for production use."
}

Les clés fondateur et d'intégration (sans accountId) sont exemptées. Les requêtes civiques sur la même clé ne changent pas. Les appels de terres légales réussis sont comptés sous legal-land, pas sous geocode.

lng et lat sont obligatoires sur chaque résultat. Une analyse réussie sans fiche legal_land (table pas encore importée, table vide, ou cellule inconnue) retourne []. Nous n'inventons pas de centroïde. Passez geometry=true (ou { geometry: true } sur le client) pour inclure le polygone lorsque la fiche en a un.

await geocoder.search('NW-25-24-1-W5', { geometry: true })

L'élément de registre legal-land-search est cette boîte de recherche avec un libellé LSD. Il n'envoie que la chaîne de requête. Ne passez pas profile= comme source de recherche.

L'analyseur fonctionne sans la table. Une coordonnée exige une fiche importée.

Un identifiant unique de puits (forme AER ST37 ou Petrinex/IHS DLS, ou un UWI SNRC de C.-B.) est le complément energy. Il sort du classement civique BM25 et retourne layer: "well", ou un 403 :

{
  "error": "Energy requires the Energy add-on",
  "code": "addon_required",
  "capability": "energy",
  "addon": "addon-energy",
  "message": "Energy requires the Energy add-on for production use."
}

Les clés fondateur et d'intégration sont exemptées. Les requêtes civiques sur la même clé ne changent pas. Un UWI introuvable (table pas encore importée, table vide, ou puits inconnu) retourne []. Nous n'inventons pas de coordonnée et ne retombons pas sur le classement d'adresses.

await geocoder.search('00/01-01-001-01W4/0')

L'élément de registre well-search est cette boîte de recherche étiquetée pour les UWI. Il n'envoie que la chaîne de requête ; la passerelle détecte UWI vs civique. Ne passez pas profile= comme source de recherche.

Les licences préfixées (W0485123, LIC 123456) suivent le même chemin. Un nombre seul, non. Les noms d'installations sont trop génériques sauf si vous passez layers=facility (ou profile=energy).

Voir Profil énergie.

Un PID ParcelMap BC à neuf chiffres (010-867-813 ou 010867813) exige la capacité legalLand, la même que la couche survey.parcels. L'export de la C.-B. n'applique aucun filtre agricole : le cadastre est du cadastre et il est restreint comme tel. Les clients Agriculture y accèdent par le groupement, qui accorde legalLand. Il sort du classement civique BM25 et retourne layer: "parcel", ou un 403 :

{
  "error": "Legal Land requires the Legal Land add-on",
  "code": "addon_required",
  "capability": "legalLand",
  "addon": "addon-legal-land",
  "message": "Legal Land requires the Legal Land add-on for production use."
}

Les appels PID réussis sont comptés sous legal-land.

Un PID introuvable (table pas encore importée, table vide, ou parcelle inconnue) retourne []. Nous n'inventons pas de centroïde. Couverture : Colombie-Britannique seulement. PIN, numéro de plan et nom de parcelle ne sont pas livrés.

await geocoder.search('010-867-813')

Identifiez la parcelle contenante avec layers=survey.parcels. Les deux chemins exigent parcels.copy dans l'image Land.

L'autre sens : un point, les polygones du catalogue qui le contiennent. C'est GET /identify, pas une nouvelle couche de géocodage. layers vaut municipalities par défaut. Les cellules d'arpentage doivent être demandées et exigent le complément legal-land. energy.wells, energy.pipelines, energy.facilities (et champs / titres) exigent le complément energy et tolèrent l'absence de table : une relation manquante ne renvoie aucune entité, pas un 500. energy.ccs et energy.geothermal ne sont pas identifiables. Les municipalités viennent de pipeline/legal-land/ (municipalities.copy dans l'image Land). Tant que ce bake n'est pas en service, results est []. La liste par bbox des mêmes tables est GET /data/query / unmap.data.query() sur Couches. Voir Couches et Couverture.

await unmap.identify({ at: [-114.07, 51.05], layers: ["municipalities"] })

Limites connues

• Une route rurale n'est jamais géocodée jusqu'à la boîte aux lettres. RR 2 Okotoks donne Okotoks, pas un point sur la route. RR 2 existe dans des centaines de collectivités et la position des boîtes ne figure dans aucun jeu de données ouvert : il n'y a rien d'honnête à retourner. Les termes de livraison de Postes Canada (RR, SS, MR, GD, SITE, COMP, BOX, STN) sont retirés avant que la requête n'atteigne le corpus, car les envoyer tels quels fait gagner les chiffres au classement et retourne n'importe quoi. Une requête faite uniquement de termes de livraison donne un 400 qui demande d'ajouter la collectivité. parseRuralRoute de @unmap/geocoding retourne les termes analysés si vous voulez les afficher à côté du résultat.
• La recherche de terres légales dépend de la table importée. L'analyseur reconnaît NW-25-24-1-W5 sans elle; les coordonnées ne reviennent qu'après le chargement de la cellule par pipeline/legal-land/.
• La recherche énergie dépend des tables importées. La détection UWI fonctionne sans elles; les coordonnées ne reviennent qu'après le chargement du puits par pipeline/energy/.

Prochaines étapes

• Les étapes 4 et 5 du Guide de démarrage cherchent un lieu puis l'épinglent sur une carte.
• Géocodage par lots pour un CSV sur votre machine, et l'exemple.
• Erreurs pour chaque statut que ce point de terminaison peut retourner, et les corps qu'il envoie.
• Composants pour une boîte de recherche prête à copier, bâtie sur cette API.