Geographies
Description​
Use this endpoint to retrieve the names and IDs of geographies (e.g. neighbourhoods, cities) associated with a specific location (lat/lng). Geographies are maintained by Local Logic's Data Team and represent a named geographical polygon used to refer to an area. These polygons are also used to compute various Local Logic insights for the various types of polygons represented in our geographies: neighborhoods, cities, zip codes, and metro areas.
The geography IDs (e.g. g10_f25dyhcn) in the returned dictionary are used to query the Local Profiles, Location Scores, Demographics, Market Statics, Value Drivers, and Similar Neighborhoods APIs to return those data products by geog_id.
Geography Levels​
Local Logic geographies exist with a hierarchy that allows multiple geographies to exist around a single location, with the ability to distinguish different types of geographies based on the geography level. Here's a summary of the possible geography levels, which can also be obtained by looking at the two-digit geography level following g in any given geography ID.
| Geography Level | Definition | Example | Availability |
|---|---|---|---|
| 10 | Neighborhood | Greenwich Village, NYC g10_dr5rsp2g | US & CA |
| 20 | Macro-neighborhood Borough / Arrondissement | Manhattan, NYC g20_dr5ruz6b | US & CA |
| 30 | City Municipality | New York, NY g30_dr5rm6xu | US & CA |
| 32 | Zip Code | Zip Code 10014 g32_dr5rezqm | US only |
| 35 | Census County Division | Manhattan g35_dr5ruy8t | US only |
| 40 | Metro Area | New York-Newark-Jersey City, NY-NJ-PA g40_dr5ryyd3 | US & CA |
| 60 | State / Province | New York state g60_drdhpv86 | US & CA |
| 70 | Country | United States g70_c2pt4mux | US & CA |
Boundary Data​
Boundaries are available for Local Logic geographies via the Geographies endpoint, leveraging the parameter option to include geometries. These boundaries can be used to display the outline of the neighborhood or city on a map, or to map locations (listings) to the boundaries of the Local Logic geography so that listings can be displayed on pages describing the neighborhood, municipality, zip code, etc.
Geographic boundaries are available in Canada and the United States. Boundaries are provided as a list of latitude/longtiude tuples describing the vertices of one or more polygons that define the geography. Here is an example of geographic boundaries for Mile End, Montréal, Canada (geog_id: g10_f25dvr2f):
Boundary data example - 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
Header​
This API uses JWT token based authentication. This JWT Bearer token is what is used to populate the
Authorization header below.
Instructions on how to retrieve this token can be found at Getting Started.
| Header | Status | Description |
|---|---|---|
| Authorization | required | Your bearer token retrieved from our authorization API, ex. Bearer eyJhbGci... |
| Accept | required | The datatype to request, this API will return application/json. |
QueryString​
Query by Latitude and Longitude​
| Parameter | Status | Description |
|---|---|---|
| lat | required | A decimal number between -90 and 90 (Latitude) |
| lng | required | A decimal number between -180 and 180 (Longitude) |
| include | optional | The only supported value is "geometry". If set, the response will contain the geometry of each of the geographies. Geometries are returned as a list of lists of tuples of lat/lng. This feature only works for Canadian geographies. |
When querying by latitude and longitude, the ordered results are by geography level, from smallest to largest.
Query by Name​
| Parameter | Status | Description |
|---|---|---|
| name | required | The name of the geography to search for. |
| language | optional | The language in which the name is provided. Accepted Values: en, fr.Default: en. |
| location_codes | optional | A comma-separated list of location codes to filter the results. If left empty then all locations are included. The codes are composed of <2 capitalized chars country code>_<2 capitalized chars state/province code>. Example values: CA_QC for Canada, Quebec. US_NY for United-States, New York. |
| levels | optional | A comma-separated list of levels to filter the results. If left empty then all levels are included. Accepted Values: 10, 20, 30, 32, 35. |
| limit | optional | How many items to return, at most. Maximum: 50 Default: 5 |
| include | optional | This parameter can be used to get the boundaries of the geography. The only supported value is "geometry". If set, the response will contain the geometry of each of the geographies. Geometries are returned as a list of lists of tuples of lat/lng. |
When querying by name, the ordered results are by similarity of the geography name to the searched text, from most similar to least similar.
Usage examples​
- NodeJS
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)
})
Response example​
{
"data": {
"type": "geographies",
"geographies": {
"g10_f25dvuzn": {
"name": {
"en": "Quartier-des-Spectacles",
"fr": "Quartier-des-Spectacles"
},
"level_type": {
"en": "neighbourhood",
"fr": "quartier"
},
"level": 10,
"country": {
"en": "Canada",
"fr": "Canada"
},
"sub_country": {
"en": "Quebec",
"fr": "Québec"
},
"metro_area": {
"en": "Greater Montreal",
"fr": "Grand Montréal"
},
"geometry": [
]
},
"g20_f25dyhf3": {
"name": {
"en": "Ville-Marie",
"fr": "Ville-Marie"
},
"level_type": {
"en": "borough",
"fr": "arrondissement"
},
"level": 20,
"country": {
"en": "Canada",
"fr": "Canada"
},
"sub_country": {
"en": "Quebec",
"fr": "Québec"
},
"metro_area": {
"en": "Greater Montreal",
"fr": "Grand Montréal"
},
"geometry": [
]
},
"g30_f25dfkk6": {
"name": {
"en": "Montréal",
"fr": "Montréal"
},
"level_type": {
"en": "city",
"fr": "ville"
},
"level": 30,
"country": {
"en": "Canada",
"fr": "Canada"
},
"sub_country": {
"en": "Quebec",
"fr": "Québec"
},
"metro_area": {
"en": "Greater Montreal",
"fr": "Grand Montréal"
},
"geometry": [
]
},
"g40_f25e4p5z": {
"name": {
"en": "Greater Montreal",
"fr": "Grand Montréal"
},
"level_type": {
"en": "metropolitan area",
"fr": "communauté métropolitaine"
},
"level": 40,
"country": {
"en": "Canada",
"fr": "Canada"
},
"sub_country": {
"en": "Quebec",
"fr": "Québec"
},
"metro_area": null,
"geometry": [
]
}
}
},
"meta": {
"order": [
"g10_f25dvuzn",
"g20_f25dyhf3",
"g30_f25dfkk6",
"g40_f25e4p5z"
]
}
}
GET v3/geographies/{geog_id}​
GET v3/geographies/{geog_id}
Header​
This API uses JWT token based authentication. This JWT Bearer token is what is used to populate the
Authorization header below.
Instructions on how to retrieve this token can be found at Getting Started.
| Header | Status | Description |
|---|---|---|
| Authorization | required | Your bearer token retrieved from our authorization API, ex. Bearer eyJhbGci... |
| Accept | required | The datatype to request, this API will return application/json. |
QueryString​
| Parameter | Status | Description |
|---|---|---|
| include | optional | This parameter can be used to get the boundaries of the geography. The only supported value is "geometry". If set, the response will contain the geometry of each of the geographies. Geometries are returned as a list of lists of tuples of lat/lng. |
Usage examples​
- NodeJS
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)
})
Response example​
{
"data": {
"type": "geographies",
"geographies": {
"g35_dnuqnr1n": {
"name": {
"en": "Whiteoak",
"fr": "Whiteoak"
},
"level_type": {
"en": "township",
"fr": "canton"
},
"level": 35,
"country": {
"en": "United States",
"fr": "États-Unis"
},
"sub_country": {
"en": "Ohio",
"fr": "Ohio"
},
"metro_area": {
"en": "Cincinnati",
"fr": "Cincinnati"
}
}
}
},
"meta": {
"order": [
"g35_dnuqnr1n"
]
}
}
Error codes​
When calling Local Logic’s API, you may receive an HTTP error code. These errors are explained below. In general, error codes starting with “4” are due to an invalid API call and can be fixed on your end, whereas error codes starting with “5” are due to server errors (that is, problems on our end). If you receive something not described here, please contact us at support@locallogic.co.
400 - BadRequest
This error code happens when the request inputs are incorrect. Use the detail field of the response for clarification. Example:
{
"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
This error code happens when your API key cannot access specific resources or locations. For example, some API keys can only access certain countries / states / provinces. Feel free to contact us for more information. Example:
{
"code": "LocalLogic.API.Unauthorized",
"detail": "Your API KEY doesn't support this region"
}
403 - Forbidden
This error code happens when you forgot to include security credentials with your request or you are requesting a parameter that you do not have access to. Example:
{
"message": "Forbidden"
}
404 - NotFound
This error code happens when we don’t have data for the requested location. For example, if you send a lat/lng pair for a location in Antarctica, we will return this error as we don’t have data for Antarctica (yet!). Example:
{
"code": "LocalLogic.API.NotFound",
"detail": "No Location Scores found for this location."
}
422 - Unprocessable Entity
This error code is returned when the correct parameters have been sent however, the data they contain is not valid. For example, if you send a lat/lng pair and the latitude is invalid (ie. not in the range [-90, 90]) and/or the longitude is invalid (ie. not in the range [-180, 180]).
{
"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
}
500 - ServerError
This error code means that an error occurred on our end. Feel free to retry the same request to see if the problem persists. If you received a lot of these errors, please contact us at support@locallogic.co Example:
{
"code": "LocalLogic.API.ServerError",
"detail": "No Location Scores found for this location."
}
502 - BadGateway
This error code means that an error came from our cloud provider. Feel free to retry the same request to see if the problem persists. Example:
{
"message": "Internal server error"
}