Aller au contenu principal

Geographies

StableAnglais et françaisÉ.-U. 🇺🇸 et Canada 🇨🇦

Description​

Utilisez ce point de terminaison pour récupérer les noms et les ID des géographies (p. ex. quartiers, villes) associées à un emplacement précis (lat/lng). Les géographies sont gérées par l'équipe des données de Local Logic et représentent un polygone géographique nommé utilisé pour désigner une zone. Ces polygones servent également à calculer diverses données d'intelligence géolocalisée de Local Logic pour les différents types de polygones représentés dans nos géographies : quartiers, villes, codes postaux et régions métropolitaines.

Les ID de géographie (p. ex. g10_f25dyhcn) dans le dictionnaire renvoyé servent à interroger les API Local Profiles, Location Scores, Demographics, Market Statics et Value Drivers, ainsi que Similar Neighborhoods, afin de renvoyer ces produits de données par geog_id.

Cas d'utilisation approuvés

Certaines API et certains SDK sont accompagnés d'un accès à l'API Geographies.

Si vous avez reçu un accès à l'API Geographies pour vous aider dans votre implémentation, veuillez noter que cette API et ses réponses doivent servir uniquement à rechercher un geog_id précis pour l'implémentation des produits Local Logic (afin de prendre en charge la requête des bonnes données communautaires par l'intermédiaire des API ou de nos widgets SDK).

Niveaux de géographie​

Les géographies de Local Logic existent selon une hiérarchie qui permet à plusieurs géographies d'exister autour d'un même emplacement, avec la possibilité de distinguer différents types de géographies selon le niveau de géographie. Voici un résumé des niveaux de géographie possibles, qui peuvent également être obtenus en examinant les deux chiffres du niveau de géographie suivant le g dans n'importe quel ID de géographie.

Niveau de géographieDéfinitionExemple (É.-U.)Exemple (CA)Disponibilité
10QuartierGreenwich Village, NYC
g10_dr5rsp2g		Trinity-Bellwoods
g10_dpz82f78		É.-U. et CA
20Macro-quartier
Arrondissement		Manhattan, NYC
g20_dr5ruz6b		Old Toronto
g20_dpz83mm2		É.-U. et CA
30Ville
Municipalité		New York, NY
g30_dr5rm6xu		Toronto, Ontario
g30_dpz89rm7		É.-U. et CA
32Code postalCode postal 10014
g32_dr5rezqm		S.O.É.-U. seulement
35Subdivision de comté américaine (recensement)Manhattan
g35_dr5ruy8t		S.O.É.-U. seulement
37Comté américain
Division de recensement canadienne (équivalent de comté)		New York County
g37_dr5ruy8t		City of Toronto (équivalent de comté)
g37_dpz89rme		É.-U. et CA
38RégionNorthern Rhode Island
g38_drmn63ct		Laurentians
g38_f269mgbu		É.-U. et CA
40Région métropolitaineNew York-Newark-Jersey City, NY-NJ-PA
g40_dr5ryyd3		Greater Toronto Area
g40_dpz3tpuh		É.-U. et CA
60État / ProvinceNew York state
g60_drdhpv86		Province of Ontario
g60_f0ghwuu0		É.-U. et CA
70PaysÉtats-Unis
g70_c2pt4mux		Canada
g70_cgk7zvu8		É.-U. et CA

geog_ids​

Les géographies sont identifiées par un identifiant geog_id dans les données et les API de Local Logic. Le format du geog_id est un détail d'implémentation. La seule garantie est qu'il s'agit d'une chaîne de caractères d'au plus 36 caractères.

attention

Même si la plupart des geog_ids ont un format similaire, l'API ne garantit pas que ce format demeurera le même. Le geog_id doit uniquement être utilisé comme référence à une géographie précise et ne doit pas être analysé pour en extraire de l'information.

Données de délimitation​

Les délimitations sont offertes pour les géographies de Local Logic par l'intermédiaire du point de terminaison Geographies, en tirant parti de l'option de paramètre permettant d'inclure les géométries. Ces délimitations peuvent servir à afficher le contour du quartier ou de la ville sur une carte, ou à associer des emplacements (inscriptions) aux délimitations de la géographie Local Logic afin que les inscriptions puissent être affichées sur des pages décrivant le quartier, la municipalité, le code postal, etc.

Les délimitations géographiques sont offertes au Canada et aux États-Unis. Les délimitations sont fournies sous forme d'une liste de tuples de latitude/longitude décrivant les sommets d'un ou de plusieurs polygones qui définissent la géographie. Voici un exemple de délimitations géographiques pour Mile End, Montréal, Canada (geog_id : g10_f25dvr2f) :

Exemple de données de délimitation - Mile End
[[[[45.53006, -73.59634], [45.52986, -73.59589], [45.52982, -73.59582], [45.52894, -73.59389],
 [45.52864, -73.59321], [45.52799, -73.59174], [45.52626, -73.58795], [45.52478, -73.58473],
 [45.52396, -73.58292], [45.52337, -73.58342], [45.52332, -73.58347], [45.52289, -73.58385],
 [45.52242, -73.58426], [45.52216, -73.58451], [45.52164, -73.58499], [45.5201, -73.58638],
 [45.51835, -73.58796], [45.51765, -73.58854], [45.51753, -73.58864], [45.51711, -73.58901],
 [45.51695, -73.58915], [45.51677, -73.58932], [45.51679, -73.58938], [45.51649, -73.58965],
 [45.51639, -73.58973], [45.51633, -73.58978], [45.5163, -73.58981], [45.51602, -73.59007],
 [45.5158, -73.59027], [45.51585, -73.59038], [45.5159, -73.59049], [45.51625, -73.59125],
 [45.5163, -73.59136], [45.51632, -73.5914], [45.51652, -73.59185], [45.51667, -73.5922],
 [45.51682, -73.59253], [45.51695, -73.59282], [45.51704, -73.59302], [45.51712, -73.5932],
 [45.51721, -73.59339], [45.51738, -73.59379], [45.51742, -73.59387], [45.51757, -73.59422],
 [45.51797, -73.59513], [45.5181, -73.59542], [45.51861, -73.59655], [45.51902, -73.59748],
 [45.51917, -73.59781], [45.51939, -73.59832], [45.51944, -73.59843], [45.51948, -73.59853],
 [45.51963, -73.59887], [45.52018, -73.6001], [45.52076, -73.60143], [45.52127, -73.60258],
 [45.52138, -73.60283], [45.52147, -73.60303], [45.52206, -73.60435], [45.52213, -73.60452],
 [45.52228, -73.60485], [45.52241, -73.60515], [45.52245, -73.60523], [45.52249, -73.60531],
 [45.52252, -73.6054], [45.52256, -73.60548], [45.5226, -73.60556], [45.52278, -73.60597],
 [45.52285, -73.60614], [45.52294, -73.60634], [45.52309, -73.60667], [45.52324, -73.607],
 [45.52335, -73.60725], [45.52349, -73.60758], [45.52366, -73.60796], [45.52376, -73.60819],
 [45.52387, -73.60843], [45.52463, -73.61015], [45.52468, -73.61026], [45.52468, -73.61026],
 [45.525, -73.61098], [45.52537, -73.61179], [45.5256, -73.61233], [45.52565, -73.61242],
 [45.52566, -73.6124], [45.5263, -73.61124], [45.52644, -73.611], [45.5277, -73.60871],
 [45.52783, -73.60839], [45.52804, -73.60786], [45.52817, -73.60739], [45.52822, -73.6072],
 [45.52823, -73.60716], [45.52825, -73.60704], [45.52828, -73.60689], [45.52829, -73.60685],
 [45.52831, -73.60672], [45.52831, -73.6067], [45.52837, -73.60626], [45.52838, -73.60619],
 [45.52838, -73.60614], [45.52839, -73.60576], [45.52837, -73.60459], [45.52837, -73.60457],
 [45.52839, -73.6035], [45.52842, -73.60238], [45.52849, -73.60167], [45.52849, -73.60167],
 [45.5285, -73.60159], [45.5285, -73.60159], [45.52854, -73.60122], [45.52857, -73.60103],
 [45.52871, -73.60014], [45.52873, -73.6], [45.52873, -73.6], [45.52878, -73.59978],
 [45.52878, -73.59977], [45.5289, -73.59929], [45.52905, -73.5988], [45.5291, -73.59861],
 [45.52916, -73.59844], [45.52916, -73.59844], [45.5293, -73.59807], [45.52931, -73.59803],
 [45.52934, -73.59796], [45.52956, -73.5974], [45.52966, -73.59715], [45.52985, -73.59678],
 [45.53004, -73.5964], [45.53007, -73.59635], [45.53006, -73.59634]]]]

GET /v3/geographies​

GET /v3/geographies

Cette API utilise l'authentification par jeton JWT. Ce jeton porteur (Bearer) JWT est ce qui est utilisé pour remplir l'en-tête Authorization ci-dessous.

Les instructions pour récupérer ce jeton se trouvent dans Premiers pas.

En-têteStatutDescription
AuthorizationrequisVotre jeton porteur récupéré depuis notre API d'autorisation, ex. Bearer eyJhbGci...
AcceptrequisLe type de données demandé; cette API retournera application/json.

Chaîne de requête​

Requête par latitude et longitude​

ParamètreStatutDescription
latrequisUn nombre décimal entre -90 et 90 (latitude)
lngrequisUn nombre décimal entre -180 et 180 (longitude)
includeoptionnelLa seule valeur prise en charge est "geometry". Si elle est définie, la réponse contiendra la géométrie de chacune des géographies. Les géométries sont renvoyées sous forme d'une liste de listes de tuples de lat/lng. Cette fonctionnalité ne fonctionne que pour les géographies canadiennes.

Lorsque vous effectuez une requête par latitude et longitude, les résultats sont classés par niveau de géographie, du plus petit au plus grand.

Requête par nom​

ParamètreStatutDescription
namerequisLe nom de la géographie à rechercher.
languageoptionnelLa langue dans laquelle le nom est fourni.
Valeurs acceptées : en, fr.
Valeur par défaut : en.
location_codesoptionnelUne liste de codes d'emplacement séparés par des virgules pour filtrer les résultats. Si le champ est laissé vide, tous les emplacements sont inclus. Les codes sont composés de <code de pays de 2 caractères majuscules>_<code d'état/province de 2 caractères majuscules>. Exemples de valeurs : CA_QC pour Canada, Québec. US_NY pour États-Unis, New York.
levelsoptionnelUne liste de niveaux séparés par des virgules pour filtrer les résultats. Si le champ est laissé vide, tous les niveaux sont inclus.
Valeurs acceptées : 10, 20, 30, 32, 35.
limitoptionnelLe nombre maximal d'éléments à renvoyer.
Maximum : 50
Valeur par défaut : 5
includeoptionnelCe paramètre peut être utilisé pour obtenir les délimitations de la géographie. La seule valeur prise en charge est "geometry". Si elle est définie, la réponse contiendra la géométrie de chacune des géographies. Les géométries sont renvoyées sous forme d'une liste de listes de tuples de lat/lng.

Lorsque vous effectuez une requête par nom, les résultats sont classés par similarité du nom de la géographie avec le texte recherché, du plus similaire au moins similaire.

Exemples d'utilisation​

require('node-fetch')('https://api.locallogic.co/v3/geographies?' + new URLSearchParams({
  lat: 41.847206,
  lng: -87.668825,
}), {
  method: 'GET',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer eyJhbGciOiJ...'
  }
})
  .then(response => response.json())
  .then(body => {
    console.log(body)
  })
  .catch(error => {
    console.log(error)
  })

Exemple de réponse​

{
    "data": {
        "type": "geographies",
        "geographies": {
            "g10_dp3wj4d7": {
                "name": {
                    "en": "Lower West Side",
                    "fr": "Lower West Side"
                },
                "level_type": {
                    "en": "neighbourhood",
                    "fr": "quartier"
                },
                "level": 10,
                "country": {
                    "en": "United States",
                    "fr": "États-Unis"
                },
                "sub_country": {
                    "en": "Illinois",
                    "fr": "Illinois"
                },
                "city": {
                    "en": "Chicago",
                    "fr": "Chicago",
                    "geog_id": "g30_dp3wh8k9"
                },
                "metro_area": {
                    "en": "Chicago-Naperville-Elgin",
                    "fr": "Chicago-Naperville-Elgin",
                    "geog_id": "g40_dp3tcmur"
                },
                "area_m2": 7576149.5,
                "bounding_box": {
                    "east": -87.63515815937586,
                    "north": 41.860018026734764,
                    "south": 41.834800982012965,
                    "west": -87.68807300499716
                },
                "centroid": {
                    "lat": 41.850266171063936,
                    "lng": -87.66756822559361
                },
                "geometry": [

                ]
            },
            "g20_dp3whpky": {
                "name": {
                    "en": "West Side",
                    "fr": "West Side"
                },
                "level_type": {
                    "en": "community",
                    "fr": "communauté"
                },
                "level": 20,
                "country": {
                    "en": "United States",
                    "fr": "États-Unis"
                },
                "sub_country": {
                    "en": "Illinois",
                    "fr": "Illinois"
                },
                "city": {
                    "en": "Chicago",
                    "fr": "Chicago",
                    "geog_id": "g30_dp3wh8k9"
                },
                "metro_area": {
                    "en": "Chicago-Naperville-Elgin",
                    "fr": "Chicago-Naperville-Elgin",
                    "geog_id": "g40_dp3tcmur"
                },
                "area_m2": 90680776.0,
                "bounding_box": null,
                "centroid": null,
                "geometry": [

                ]
            },
            "g30_dp3wh8k9": {
                "name": {
                    "en": "Chicago",
                    "fr": "Chicago"
                },
                "level_type": {
                    "en": "city",
                    "fr": "ville"
                },
                "level": 30,
                "country": {
                    "en": "United States",
                    "fr": "États-Unis"
                },
                "sub_country": {
                    "en": "Illinois",
                    "fr": "Illinois"
                },
                "city": null,
                "metro_area": {
                    "en": "Chicago-Naperville-Elgin",
                    "fr": "Chicago-Naperville-Elgin",
                    "geog_id": "g40_dp3tcmur"
                },
                "area_m2": 722438400.0,
                "bounding_box": {
                    "east": -87.524165,
                    "north": 42.0231296710675,
                    "south": 41.644286,
                    "west": -87.940097
                },
                "centroid": {
                    "lat": 41.83753543223453,
                    "lng": -87.68657967628782
                },
                "geometry": [

                ]
            },
            "g32_dp3whfre": {
                "name": {
                    "en": "Zip Code 60608",
                    "fr": "Zip Code 60608"
                },
                "level_type": {
                    "en": "postal code",
                    "fr": "code postal"
                },
                "level": 32,
                "country": {
                    "en": "United States",
                    "fr": "États-Unis"
                },
                "sub_country": {
                    "en": "Illinois",
                    "fr": "Illinois"
                },
                "city": null,
                "metro_area": {
                    "en": "Chicago-Naperville-Elgin",
                    "fr": "Chicago-Naperville-Elgin",
                    "geog_id": "g40_dp3tcmur"
                },
                "area_m2": 16791314.0,
                "bounding_box": {
                    "east": -87.63856,
                    "north": 41.869295,
                    "south": 41.830238,
                    "west": -87.703045
                },
                "centroid": {
                    "lat": 41.848893003797045,
                    "lng": -87.67143179512888
                },
                "geometry": [

                ]
            },
            "g35_dp3wh8n8": {
                "name": {
                    "en": "Chicago",
                    "fr": "Chicago"
                },
                "level_type": {
                    "en": "city",
                    "fr": "subdivision du comté"
                },
                "level": 35,
                "country": {
                    "en": "United States",
                    "fr": "États-Unis"
                },
                "sub_country": {
                    "en": "Illinois",
                    "fr": "Illinois"
                },
                "city": null,
                "metro_area": {
                    "en": "Chicago-Naperville-Elgin",
                    "fr": "Chicago-Naperville-Elgin",
                    "geog_id": "g40_dp3tcmur"
                },
                "area_m2": 592966336.0,
                "bounding_box": {
                    "east": -87.524165,
                    "north": 42.0231296710675,
                    "south": 41.644286,
                    "west": -87.940097
                },
                "centroid": {
                    "lat": 41.83594554913905,
                    "lng": -87.6837546791974
                },
                "geometry": [

                ]
            },
            "g37_dp3wmdf4": {
                "name": {
                    "en": "Cook County",
                    "fr": "Cook County"
                },
                "level_type": {
                    "en": "county",
                    "fr": "comté"
                },
                "level": 37,
                "country": {
                    "en": "United States",
                    "fr": "États-Unis"
                },
                "sub_country": {
                    "en": "Illinois",
                    "fr": "Illinois"
                },
                "city": null,
                "metro_area": {
                    "en": "Chicago-Naperville-Elgin",
                    "fr": "Chicago-Naperville-Elgin",
                    "geog_id": "g40_dp3tcmur"
                },
                "area_m2": 4233681920.0,
                "bounding_box": {
                    "east": -87.111162,
                    "north": 42.154292,
                    "south": 41.469705,
                    "west": -88.263641
                },
                "centroid": {
                    "lat": 41.89542888222109,
                    "lng": -87.64614087645053
                },
                "geometry": [

                ]
            },
            "g40_dp3tcmur": {
                "name": {
                    "en": "Chicago-Naperville-Elgin",
                    "fr": "Chicago-Naperville-Elgin"
                },
                "level_type": {
                    "en": "metropolitan area",
                    "fr": "communauté métropolitaine"
                },
                "level": 40,
                "country": {
                    "en": "United States",
                    "fr": "États-Unis"
                },
                "sub_country": {
                    "en": "Illinois",
                    "fr": "Illinois"
                },
                "city": null,
                "metro_area": null,
                "area_m2": 24808267776.0,
                "bounding_box": {
                    "east": -86.929353,
                    "north": 42.66990599999999,
                    "south": 40.736509999999996,
                    "west": -88.942146
                },
                "centroid": {
                    "lat": 41.82483936284782,
                    "lng": -87.82961900377116
                },
                "geometry": [

                ]
            }
        }
    },
    "meta": {
        "order": [
            "g10_dp3wj4d7",
            "g20_dp3whpky",
            "g30_dp3wh8k9",
            "g32_dp3whfre",
            "g35_dp3wh8n8",
            "g37_dp3wmdf4",
            "g40_dp3tcmur"
        ]
    }
}

GET /v3/geographies/{geog_id}​

GET /v3/geographies/{geog_id}

Cette API utilise l'authentification par jeton JWT. Ce jeton porteur (Bearer) JWT est ce qui est utilisé pour remplir l'en-tête Authorization ci-dessous.

Les instructions pour récupérer ce jeton se trouvent dans Premiers pas.

En-têteStatutDescription
AuthorizationrequisVotre jeton porteur récupéré depuis notre API d'autorisation, ex. Bearer eyJhbGci...
AcceptrequisLe type de données demandé; cette API retournera application/json.

Chaîne de requête​

ParamètreStatutDescription
includeoptionnelCe paramètre peut être utilisé pour obtenir les délimitations de la géographie. La seule valeur prise en charge est "geometry". Si elle est définie, la réponse contiendra la géométrie de chacune des géographies. Les géométries sont renvoyées sous forme d'une liste de listes de tuples de lat/lng.

Exemples d'utilisation​

require('node-fetch')('https://api.locallogic.co/v3/geographies/g35_dnuqnr1n'), {
  method: 'GET',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer eyJhbGciOiJ...'
  }
})
  .then(response => response.json())
  .then(body => {
    console.log(body)
  })
  .catch(error => {
    console.log(error)
  })

Exemple de réponse​

{
    "data": {
        "type": "geographies",
        "geographies": {
            "g35_dnuqnr1n": {
                "name": {
                    "en": "Whiteoak",
                    "fr": "Whiteoak"
                },
                "level_type": {
                    "en": "township",
                    "fr": "subdivision du comté"
                },
                "level": 35,
                "country": {
                    "en": "United States",
                    "fr": "États-Unis"
                },
                "sub_country": {
                    "en": "Ohio",
                    "fr": "Ohio"
                },
                "city": null,
                "metro_area": null,
                "area_m2": 78415792.0,
                "bounding_box": {
                    "east": -83.681276,
                    "north": 39.112221,
                    "south": 39.020173,
                    "west": -83.81926
                },
                "centroid": {
                    "lat": 39.063058148847595,
                    "lng": -83.74710991954323
                },
                "geometry": [

                ]
            }
        }
    },
    "meta": {
        "order": [
            "g35_dnuqnr1n"
        ]
    }
}

Codes de réponse​

Lorsque vous appelez l'API de Local Logic, vous pouvez recevoir un code de réponse HTTP indiquant une erreur ou une absence de données. Ces erreurs sont expliquées ci-dessous.

En général, les codes d'erreur commençant par « 4 » sont dus à un appel d'API invalide et peuvent être corrigés de votre côté, alors que les codes d'erreur commençant par « 5 » sont dus à des erreurs de serveur (c'est-à-dire des problèmes de notre côté). Si vous recevez quelque chose qui n'est pas décrit ici, veuillez communiquer avec nous à support@locallogic.co.

204 - No Content

Ce « code d'erreur » n'en est pas un et se produit lorsque nous n'avons pas les données requises pour un emplacement précis. Par exemple, si vous envoyez une paire lat/lng pour obtenir des scores dans des régions inhabitées du nord du Canada, nous pouvons retourner une réponse 204 vide, car nous reconnaissons l'emplacement, mais nous ne calculons pas de scores dans des endroits aussi éloignés, donc il n'y a rien à retourner.

400 - BadRequest

Ce code d'erreur se produit lorsque les données saisies dans la requête sont incorrectes. Utilisez le champ detail de la réponse pour obtenir des précisions. Exemple :

{
  "code": "LocalLogic.API.BadRequest",
  "detail": "ValidationErrors: AroundEndpoint is invalid:\n\tinclude is invalid: \"bad_input\" is not an acceptable value: \"groceries\", \"restaurants\", \"nightlife\", \"cafes\", \"shopping\", \"daycares\", \"primary_schools\", \"high_schools\""
}

401 - Unauthorized

Ce code d'erreur se produit lorsque votre clé API ne peut pas accéder à certaines ressources ou à certains emplacements. Par exemple, certaines clés API ne peuvent accéder qu'à certains pays, états ou provinces. N'hésitez pas à communiquer avec nous pour plus d'information.

{
  "code": "LocalLogic.API.Unauthorized",
  "detail": "Your API KEY doesn't support this region"
}

403 - Forbidden

Ce code d'erreur se produit lorsque vous avez oublié d'inclure les identifiants de sécurité dans votre requête ou lorsque vous demandez un paramètre auquel vous n'avez pas accès.

{
  "message": "Forbidden"
}

404 - NotFound

Ce code d'erreur se produit lorsque nous n'avons pas de données pour l'emplacement demandé. Par exemple, si vous envoyez une paire lat/lng pour un emplacement en Antarctique, nous retournerons cette erreur, car nous n'avons pas (encore!) de données pour l'Antarctique.

{
  "code": "LocalLogic.API.NotFound",
  "detail": "No Location Scores found for this location."
}

422 - Unprocessable Entity

Ce code d'erreur est retourné lorsque les bons paramètres ont été envoyés, mais que les données qu'ils contiennent ne sont pas valides. Par exemple, si vous envoyez une paire lat/lng et que la latitude est invalide (c.-à-d. hors de la plage [-90, 90]) ou que la longitude est invalide (c.-à-d. hors de la plage [-180, 180]). Le message retourné expliquera le problème précis avec vos paramètres qui les rend invalides.

{
  "message": "Latitude must be within [-90, 90], Longitude must be within [-180, 180], Requires at least lat/lng pair, or geography_ids. None supplied.",
  "code": "LocalLogic.API.BadRequest",
  "statusCode": 422
}

429 - Too Many Requests

Ce code d'erreur peut être retourné lorsque vous devez limiter le débit de vos requêtes. À l'interne, nous établissons des limites qui dépassent toutes les limites contractuelles pouvant entraîner le retour de ce code d'erreur. Si vous avez des questions ou si vous voyez cette erreur, veuillez communiquer avec nous à support@locallogic.co.

500 - ServerError

Ce code d'erreur signifie qu'une erreur s'est produite de notre côté. N'hésitez pas à réessayer la même requête pour voir si le problème persiste. Si vous recevez beaucoup de ces erreurs, veuillez communiquer avec nous à support@locallogic.co.

{
  "code": "LocalLogic.API.ServerError",
  "detail": "No Location Scores found for this location."
}

502 - BadGateway

Ce code d'erreur signifie qu'une erreur provient de notre fournisseur infonuagique. N'hésitez pas à réessayer la même requête pour voir si le problème persiste.

{
  "message": "Internal server error"
}