Custom Neighborhoods
Description
Nos points de terminaison pour les quartiers personnalisés (Custom Neighborhoods) permettent aux clients de mettre en file d'attente des géographies personnalisées et privées afin qu'elles soient traitées lors des mises à jour régulières des quartiers de Local Logic, qui permettent de traiter et d'ajouter de nouvelles zones. Cette fonctionnalité permet de réaliser des demandes de géographies personnalisées à grande échelle et de les rendre offertes de façon privée. Ces polygones servent également à calculer diverses données de Local Logic, telles que les données Demographics, les Location Scores, le texte de Profiles et les Market Statistics (aux États-Unis).
Cette fonctionnalité nécessite des autorisations précises qui doivent être activées. Si cette fonctionnalité vous intéresse mais que vous n'y avez pas accès pour mettre en file d'attente des quartiers personnalisés, veuillez communiquer avec support@locallogic.co.
Dans l'ensemble de ce document, chaque demande est désignée comme une “géographie personnalisée”, car cette fonctionnalité peut être utilisée pour définir des limites de ville personnalisées, des régions personnalisées et plus encore, au-delà de la taille et de l'échelle habituelles d'un “quartier”.
Concepts
Accès aux géographies personnalisées
Les géographies personnalisées sont liées à l'entité de compte unique associée à l'ensemble de la suite de produits Local Logic. Nous pouvons restreindre l'accès pour gérer et demander de nouvelles géographies personnalisées à un seul ensemble d'identifiants, mais une fois qu'elles sont entièrement traitées, la possibilité de charger des widgets et d'interroger des données concernant ces quartiers ou géographies est limitée à l'ensemble des identifiants liés au même client.
Cela signifie qu'aucun autre compte Local Logic ne pourra voir, charger ou récupérer des données pour ces quartiers, ce qui les rend en fait privés et visibles uniquement pour l'ensemble des identifiants qui vous sont associés, ainsi que pour l'équipe de Local Logic afin de vous aider dans l'utilisation des produits.
Cycle de vie de la demande
Les statuts de traitement suivants sont renvoyés par les points de terminaison POST et GET décrits ci-dessous afin de permettre le suivi de l'achèvement et de la publication de la géographie personnalisée pour qu'elle soit offerte par l'intermédiaire des API de Local Logic et des IO Reports.
| Statut de traitement | Explication |
|---|---|
PUBLICATION_PENDING | Le statut initial de la demande. Cela indique que la demande est en attente du début de la prochaine mise à jour générale. |
PUBLICATION_PROCESSING | Cela indique que la demande est en cours de traitement (la mise à jour est en cours). Cela se produit généralement de quelques jours à une semaine avant que les données soient publiées ou offertes. |
PUBLISHED | Cela indique que la demande a été traitée et que la géographie ou le quartier personnalisé a été publié. Cela signifie que la géographie est offerte de façon générale pour l'ensemble du compte dans tous les produits Local Logic – comme les SDK NHWrap et les API Local Insights. À ce stade, la géographie personnalisée aura un geog_id nouveau (ou mis à jour) qui pourra être utilisé pour configurer des pages communautaires ou accéder à des données dans les API Local Logic. |
DEPRECATION_PENDING | Cela signifie que la dépréciation de la géographie a été mise en file d'attente, en attente de la prochaine mise à jour générale des quartiers. |
DEPRECATION_PROCESSING | Cela indique que la demande de dépréciation de la géographie est en cours de traitement (la mise à jour est en cours). Cela se produit généralement de quelques jours à une semaine avant que la dépréciation soit terminée. |
DEPRECATED | Cela indique que la demande a été traitée et que la géographie ou le quartier personnalisé a été déprécié. Afin de ne pas briser les pages communautaires qui utilisent la géographie, celle-ci continuera de fonctionner dans les SDK NHWrap de Local Logic et dans nos API lorsque le geog_id est fourni, mais elle ne sera plus consultable ni mise à jour à l'avenir. |
Mises à jour des quartiers de Local Logic
Actuellement, Local Logic publie un lot des quartiers les plus récents une fois par mois (avec l'objectif de le faire deux fois par mois dans le futur). Ces mises à jour des quartiers calculent toutes les données des quartiers sur quelques jours à partir de nos sources les plus récentes, et veillent à ce que toutes les données soient à jour pour l'ensemble de nos géographies, y compris toute demande en attente pour de nouvelles géographies.
Une fois la mise à jour des quartiers terminée, la demande de géographie (le “quartier personnalisé”) est publiée et devient offerte avec toutes les données pouvant être calculées pour cette géographie : les données Demographics, les Location Scores, le texte de Profiles généré et les Market Statistics.
Après la publication de chaque mise à jour des quartiers, il sera possible de recevoir une notification par courriel confirmant l'achèvement de la mise à jour; à ce moment, les geog_id peuvent être récupérés pour toute demande incluse, puis les pages communautaires peuvent être mises en œuvre, ou les appels API vers Local Logic commenceront à renvoyer des informations pour ces zones.
Données de délimitation
Les limitations suivantes s'appliquent aux polygones définis pour les géographies personnalisées :
- Le centroïde de la géographie personnalisée doit se trouver dans les limites accessibles définies pour le compte (qui peuvent se situer dans un état, une province ou un territoire précis; pour les clients ayant un accès complet aux données de Local Logic, cela signifie que le centroïde doit se trouver au Canada ou aux États-Unis).
- La taille maximale permise pour la définition est de 20 000 km2 (7 722 milles carrés – une superficie plus grande que le Connecticut, ou 4 fois la taille de l'Île-du-Prince-Édouard, Canada).
- La taille minimale permise pour la définition est de 0,1 km2 (0,039 mille carré, soit environ 24 acres).
POST /v3/geographies/custom
POST /v3/geographies/custom
Ce point de terminaison est utilisé pour soumettre et mettre en file d'attente un quartier personnalisé aux fins de traitement. Il renvoie (en cas de succès) un ID généré qui peut être utilisé pour suivre la demande et récupérer un geog_id pour la mise en œuvre de la page communautaire une fois le quartier publié.
En-tête
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ête | Statut | Description |
|---|---|---|
| Authorization | requis | Votre jeton porteur récupéré depuis notre API d'autorisation, ex. Bearer eyJhbGci... |
| Accept | requis | Le type de données demandé; cette API retournera application/json. |
Paramètres du corps
| Paramètre | Statut | Description |
|---|---|---|
| name_en | requis | Le nom du quartier ou de la géographie en anglais, qui sera utilisé pour le texte généré et pour l'affichage de la géographie dans les produits et les API de Local Logic. |
| name_fr | optionnel | Le nom du quartier ou de la géographie en français, qui sera utilisé pour générer le texte de profil en français et pour l'affichage en français au Canada. Valeur par défaut : lorsqu'il n'est pas fourni, le nom anglais sera également utilisé pour le texte français pour les géographies au Canada. |
| boundaries | requis | Les délimitations de la géographie personnalisée au format WKT. Ces représentations polygonales peuvent être générées ou vérifiées manuellement à l'aide d'outils gratuits comme WKT Map. Celles-ci sont présumées être fournies selon le système (SRID=4326)[https://fr.wikipedia.org/wiki/Syst%C3%A8me_de_coordonn%C3%A9es_(cartographie)] (longitude, latitude). Il n'est pas nécessaire de fournir le SRID. L'outil gratuit WKT Map mentionné ci-dessus prend en charge ce système automatiquement, mais certaines délimitations et certains polygones dans les outils SIG peuvent nécessiter une conversion vers ce système de référence. Les polygones représentant les délimitations sont assujettis aux limitations décrites dans la section sur les limitations des polygones ci-dessus. |
| type | requis | Une classification du type de géographie qui est à la fois utilisée dans le texte généré et pour déterminer le niveau de géographie. Utilisez la description de type qui vous semble appropriée, et nous nous occupons du reste! La liste des types acceptés est la suivante : - NEIGHBORHOOD- COMMUNITY- CITY- TOWN- VILLAGE- NEIGHBOURHOOD- RESERVE- MUNICIPALITY- TOWNSHIP- RURAL_MUNICIPALITY- MUNICIPAL_DISTRICT- BOROUGH- SECTOR- REGION- POSTAL_CITY |
Exemples d'utilisation
- Python
import requests
response = requests.post(
"https://api.locallogic.co/v3/geographies/custom",
headers={
"Accept": "application/json",
"Authorization": "Bearer eyJhbGciOiJ..."},
json={
"boundaries": "POLYGON ((-73.989176 40.716704, -73.992201 40.717672, -73.993435 40.715363, -73.993971 40.714289, -73.991235 40.714493, -73.991128 40.714712, -73.990248 40.714419, -73.990216 40.71468, -73.989176 40.716704))",
"name_en": "Dime Square",
"type": "NEIGHBORHOOD"
}
)
print(response.json())
Exemple de réponse
La réponse renverra un nouvel ID (geo_entity_id) permettant de suivre la demande jusqu'à la publication des données et à la disponibilité d'une page communautaire pour la géographie personnalisée, ce qui dépend du cycle de mise à jour des quartiers de Local Logic.
Cet ID peut être utilisé pour apporter des modifications à la géographie personnalisée et pour obtenir un geog_id pour la page communautaire et les requêtes API de données une fois que les données sont offertes.
{
"geo_entity_id": "a98f6782-fbb1-4ba2-8f40-381424990637",
"processing_status": "PUBLICATION_PENDING"
}
PATCH /v3/geographies/custom/{geo_entity_id}
Ce point de terminaison est utilisé pour mettre à jour une géographie personnalisée. Les géographies personnalisées peuvent être mises à jour à l'aide du geo_entity_id avant la publication (moment où les données deviennent offertes dans les API de Local Logic, les widgets SDK et les IO Reports), ou après la publication de la géographie.
Lorsque la géographie a déjà été publiée, toute mise à jour soumise par PATCH attend la prochaine mise à jour des quartiers de Local Logic pour être reflétée dans les produits Local Logic.
PATCH /v3/geographies/custom/{geo_entity_id}
En-tête
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ête | Statut | Description |
|---|---|---|
| Authorization | requis | Votre jeton porteur récupéré depuis notre API d'autorisation, ex. Bearer eyJhbGci... |
| Accept | requis | Le type de données demandé; cette API retournera application/json. |
Paramètres du corps
Pour appeler ce point de terminaison, les mêmes paramètres de requête d'en-tête que ceux du point de terminaison POST sont requis. Seuls les paramètres du corps qui sont mis à jour doivent être inclus dans le corps JSON avec les nouvelles valeurs.
Exemples d'utilisation
- Python
import requests
response = requests.patch(
"https://api.locallogic.co/v3/geographies/custom/a98f6782-fbb1-4ba2-8f40-381424990637",
headers={
"Accept": "application/json",
"Authorization": "Bearer eyJhbGciOiJ..."},
json={
"name_en": "Dimes Square"
}
)
print(response.json())
Exemple de réponse
{
"geo_entity_id": "a98f6782-fbb1-4ba2-8f40-381424990637",
"processing_status": "PUBLICATION_PENDING"
}
GET /v3/geographies/custom/{geo_entity_id}
Ce point de terminaison est utilisé pour récupérer les détails de la demande de géographie personnalisée, à l'aide du geo_entity_id renvoyé initialement. Ce point de terminaison renvoie les derniers détails de la mise à jour la plus récente de la géographie personnalisée, décrits ci-dessous.
GET /v3/geographies/custom/{geo_entity_id}
En-tête
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ête | Statut | Description |
|---|---|---|
| Authorization | requis | Votre jeton porteur récupéré depuis notre API d'autorisation, ex. Bearer eyJhbGci... |
| Accept | requis | Le type de données demandé; cette API retournera application/json. |
Champs de réponse
| Paramètre | Description |
|---|---|
| geo_entity_id | L'ID de la demande de géographies personnalisées. |
| name_en | Le nom du quartier ou de la géographie en anglais. |
| name_fr | Le nom du quartier ou de la géographie en français. |
| boundaries | Les délimitations de la géographie personnalisée au format WKT. |
| type | Une classification du type de géographie. La liste des types énumérés est fournie dans le tableau des paramètres du corps POST V3 ci-dessus. |
| processing_status | Le statut de la dernière demande de geo_entity_id effectuée. Les valeurs possibles pour ce statut sont indiquées ci-dessous : - PUBLICATION_PENDING- PUBLICATION_PROCESSING- PUBLISHED- DEPRECATION_PENDING- DEPRECATION_PROCESSING- DEPRECATED |
| geog_id | Le geog_id qui peut être utilisé comme paramètre d'API ou comme option de SDK Local Logic pour instancier les SDK NeighborhoodWrap. Cela n'est offert que lorsque la dernière demande de géographie personnalisée a été traitée et est publiée en production. |
| published_at | L'horodatage du moment où le geo_entity_id a été publié et rendu offert dans les produits Local Logic. |
| updated_at | L'horodatage de la mise à jour la plus récente de la géographie personnalisée par l'intermédiaire des points de terminaison POST ou PATCH de ce document. |
Exemples d'utilisation
- Python
import requests
response = requests.get(
"https://api.locallogic.co/v3/geographies/custom/a98f6782-fbb1-4ba2-8f40-381424990637",
headers={
"Accept": "application/json",
"Authorization": "Bearer eyJhbGciOiJ..."}
)
print(response.json())
Exemple de réponse
{
"boundaries": "POLYGON ((-73.989176 40.716704, -73.992201 40.717672, -73.993435 40.715363, -73.993971 40.714289, -73.991235 40.714493, -73.991128 40.714712, -73.990248 40.714419, -73.990216 40.71468, -73.989176 40.716704))",
"geo_entity_id": "a98f6782-fbb1-4ba2-8f40-381424990637",
"geog_id": null,
"processing_status": "PUBLICATION_PENDING",
"published_at": null,
"name_en": "Dimes Square",
"name_fr": "Dimes Square",
"type": "NEIGHBOURHOOD",
"updated_at": "2026-07-09T15:47:34.433625Z"
}
GET /v3/geographies/custom
Ce point de terminaison est utilisé pour récupérer les détails de toutes les demandes de géographies personnalisées soumises pour l'ensemble du compte (puisque les géographies personnalisées sont partagées entre les identifiants). Le point de terminaison prend également en charge la recherche et la pagination. Les délimitations sont offertes lors d'une requête avec un geo_entity_id précis, mais elles sont NULL lors d'une requête ou de la récupération de plusieurs géographies personnalisées.
GET /v3/geographies/custom
En-tête
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ête | Statut | Description |
|---|---|---|
| Authorization | requis | Votre jeton porteur récupéré depuis notre API d'autorisation, ex. Bearer eyJhbGci... |
| Accept | requis | Le type de données demandé; cette API retournera application/json. |
Paramètres de requête
| Paramètre | Statut | Description |
|---|---|---|
| page | optionnel | La page des résultats à renvoyer. Valeur par défaut : 1 |
| page_size | optionnel | Le nombre de résultats à renvoyer par page, jusqu'à concurrence de 100. Valeur par défaut : 20 |
| search | optionnel | Une chaîne de caractères pour rechercher des demandes de quartiers personnalisés par nom. Elle recherche la chaîne (sans distinction de la casse) dans les noms de tous les quartiers demandés offerts. Longueur maximale : 200 |
Exemples d'utilisation
- Python
import requests
response = requests.get(
"https://api.locallogic.co/v3/geographies/custom",
headers={
"Accept": "application/json",
"Authorization": "Bearer eyJhbGciOiJ..."}
)
print(response.json())
Exemple de réponse
{
"items": [
{
"boundaries": null,
"geo_entity_id": "437b7340-f068-4f2a-8d07-1a7d23cfdf32",
"geog_id": null,
"processing_status": "PUBLICATION_PROCESSING",
"published_at": null,
"name_en": "Test 1",
"name_fr": "Test 1",
"type": "NEIGHBOURHOOD",
"updated_at": "2026-05-21T18:20:17.978013Z"
},
{
"boundaries": null,
"geo_entity_id": "6f2b10a0-18f1-4ade-8494-7fd2e27b2898",
"geog_id": null,
"processing_status": "PUBLICATION_PROCESSING",
"published_at": null,
"name_en": "Genesee Depot",
"name_fr": "Genesee Depot",
"type": "NEIGHBORHOOD",
"updated_at": "2026-04-15T14:16:34.677505Z"
},
{
"boundaries": null,
"geo_entity_id": "0475fb33-1ef8-4db8-ab9f-2ff259ef864d",
"geog_id": "g30_dpdgequz",
"processing_status": "PUBLISHED",
"published_at": "2026-02-06T20:01:43.613672Z",
"name_en": "Zeeland",
"name_fr": "Zeeland",
"type": "POSTAL_CITY",
"updated_at": "2026-01-15T19:39:39.237494Z"
},
{
"boundaries": null,
"geo_entity_id": "f6c25e55-8f2d-4fc6-b99d-31e0c8062e9b",
"geog_id": "g30_dpjeq4v3",
"processing_status": "PUBLISHED",
"published_at": "2026-02-06T20:01:43.613672Z",
"name_en": "Zanesville",
"name_fr": "Zanesville",
"type": "POSTAL_CITY",
"updated_at": "2026-01-15T19:39:39.074043Z"
},
{
"boundaries": null,
"geo_entity_id": "3f18d4a7-6314-4f66-996f-689fc9d5cf1b",
"geog_id": "g30_dr17qmp0",
"processing_status": "PUBLISHED",
"published_at": "2026-02-06T20:01:43.613672Z",
"name_en": "York",
"name_fr": "York",
"type": "POSTAL_CITY",
"updated_at": "2026-01-15T19:39:38.823534Z"
}
],
"total": 12071,
"page": 1,
"page_size": 5
}
DELETE /v3/geographies/custom/{geo_entity_id}
Ce point de terminaison est utilisé pour déprécier la géographie personnalisée, à l'aide de son geo_entity_id. Ce point de terminaison marque la géographie comme n'étant plus nécessaire et la retire des réponses automatiques et des appels à /v3/geographies, de sorte que, par défaut, elle ne soit plus offerte dans les produits Local Logic après la prochaine mise à jour des quartiers de Local Logic.
DELETE /v3/geographies/custom/{geo_entity_id}
En-tête
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ête | Statut | Description |
|---|---|---|
| Authorization | requis | Votre jeton porteur récupéré depuis notre API d'autorisation, ex. Bearer eyJhbGci... |
| Accept | requis | Le type de données demandé; cette API retournera application/json. |
Exemples d'utilisation
- Python
import requests
response = requests.delete(
"https://api.locallogic.co/v3/geographies/custom/a98f6782-fbb1-4ba2-8f40-381424990637",
headers={
"Accept": "application/json",
"Authorization": "Bearer eyJhbGciOiJ..."}
)
print(response.json())
Exemple de réponse
Ce point de terminaison renverra un code de réponse 204 en cas de succès, sans contenu.
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"
}