Skip to main content

Location Snapshot

Stable
Only available in EnglishUS πŸ‡ΊπŸ‡Έ and Canada πŸ‡¨πŸ‡¦

Query to get a location snapshot: an aggregated view of Local Logic data around a given location. This endpoint provides four sets of Local Logic insights around a given latitude and longitude:

  • Demographics data around the provided location
  • Points of Interest counts by category around the provided location
  • Local Logic Location Scores around the provided location
  • Local Logic measures around the provided location, which includes calculations of access, distance, noise, and quality. For example:
    • Nearest general grocery store proximity
    • Access to coffee shops
    • Traffic noise
    • Infrastructure unpleasantness for pedestrians

GET v3/data​

The requested demographics, POI counts, location scores, and Local Logic measures can be retrieved for a specific location or a custom polygon using this request.

GET v3/data

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.

HeaderStatusDescription
AuthorizationrequiredYour bearer token retrieved from our authorization API, ex. Bearer eyJhbGci...
AcceptrequiredThe datatype to request, this API will return application/json.

QueryString​

The region to be queried by the endpoint can be defined two ways: (1) by specifying a lat/lng coordinate, with optional radius/radius_unit parameters, (2) or by providing a polygon parameter.

When using the lat/lng coordinate query method without specifying radius/radius_unit parameters, the endpoint will return demographics data within 500 m, points of interest counts within 5km, and measures and scores for the exact location provided. When including radius/radius_unit parameters, the resulting circular area around the lat/lng coordinate will be queried. radius_unit can be either meter or mile.

When using the polygon query method, the demographic data returned will cover residents of the region defined by the polygon area. Polygons are specified using the WKT format. The only accepted type is POLYGON, and holes are not supported. Each polygon point must be defined as a lng/lat coordinate.

API Limitations

  1. The polygon query string has been limited to 5000 chars.
  2. The max north/south east/west distance accepted is 0.5 degrees.
  3. The max count of north/south east/west level 6 geohashes is 1000.
warning

WKT works on x/y planes. Therefore, the coordinates must be sent as lng/lat instead of lat/lng.

ParameterStatusDescription
includerequiredComma separated strings of data to be returned.
Accepted values are demographics, measures_all, pois_count, and scores_all.
latoptionalA decimal number between -90 and 90 (Latitude)
lngoptionalA decimal number between -180 and 180 (Longitude)
radiusoptionalA positive float number (Circle radius)
radius_unitoptionalThe unit type of the radius.
Available: meter, mile.
Default: meter
polygonoptionalList of 2D lng/lat points that define a 2D polygon, using the WKT representation

Usage examples​

require('node-fetch')('https://api.locallogic.co/v3/data?' + new URLSearchParams({
lat: 41.847206,
lng: -87.668825,
include: 'demographics,scores_all,measures_all,pois_count'
}), {
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": {
"demographics": {
"commute_mode": {
"type": "percent",
"variables": [
{
"variable": "cmtr_transt",
"value": 0,
"label": "Transit"
},
...
],
"label": "Commute mode"
},
"population_total": {
...
},
...
},
"scores": {
"high_schools": "0.06532",
"primary_schools": "3.75381",
...
},
"pois": {
"counts": {
"total_count": 1927,
"total_by_category": {
"libraries": 4,
"alcohol": 33,
"shops_and_services": 1740,
"home_improvement": 18,
...
}
}
},
"measures": {
"nearest_general_grocery_store_proximity": 4.68047,
"nearest_fitness_establishment_proximity": 4.89759,
"nearest_clothing_and_accessory_store_proximity": 4.89759,
"coffee_shop_access": 2.12512,
...
}
},
"meta": {
"message": "Successfully called v3/data API.",
"type": "LocalLogic.API.Success",
"statusCode": 200
}
}

In the above example of returned data, each of the four components of the Data response are provided:

  • Demographics data depends on the available attributes by country. See that documentation page for more information on responses.
  • Local Logic Location Scores around the provided location. All available scores at the location are provided on scale of 0 to 5, without any rounding.
  • Points of Interest counts by category around the provided location, including the total POI count. If more detail on POIs is required, users will need to call one of our POI endpoints directly with proper access.
  • Local Logic measures around the provided location

Local Logic Measures​

Local Logic Measures are used to quantify location characteristics on a more granular level that Location Scores. Here's a list of all of the measures that can be returned by the Data endpoint:

MeasureDescription
bus_service_accessA measure, on a 0 to 5 scale, of how easy it is to get to city bus stops from this location, weighted by how frequently buses come to them. Higher values indicate that there are more reachable bus stops, that they are closer, and that bus frequency is higher.
shops_and_services_accessA measure, on a 0 to 5 scale, of how easy it is to get to shops and services from this location. Higher values indicate that there are more reachable shops and services, and that they are closer.
coffee_shop_accessA measure, on a 0 to 5 scale, of how easy it is to get to coffee shops from this location. Higher values indicate that there are more reachable coffee shops, and that they are closer.
casino_accessA measure, on a 0 to 5 scale, of how easy it is to get to casinos from this location. Higher values indicate that there are more reachable casinos, and that they are closer.
clothing_and_accessory_store_accessA measure, on a 0 to 5 scale, of how easy it is to get to clothing and accessory stores from this location. Higher values indicate that there are more reachable clothing and accessory stores, and that they are closer.
common_needs_accessA measure, on a 0 to 5 scale, of how easy it is to get to common needs from this location. Higher values indicate that there are more reachable common needs, and that they are closer. Common needs include hairdressers, hardware stores, liquor stores, banks, post offices, convenience stores, and laundry services. Groceries and pharmacies have separate measures.
department_store_accessA measure, on a 0 to 5 scale, of how easy it is to get to department stores from this location. Higher values indicate that there are more reachable department stores, and that they are closer.
entertainment_venue_accessA measure, on a 0 to 5 scale, of how easy it is to get to entertainment venues from this location. Higher values indicate that there are more reachable entertainment venues, and that they are closer. Entertainment venues include music venues, live theaters, cinemas, and performing arts venues.
fitness_establishment_accessA measure, on a 0 to 5 scale, of how easy it is to get to fitness establishments from this location. Higher values indicate that there are more reachable fitness establishments, and that they are closer. Fitness establishments include gyms, yoga studios, and pools.
healthy_restaurant_accessA measure, on a 0 to 5 scale, of how easy it is to get to healthy restaurants from this location. Higher values indicate that there are more reachable healthy restaurants, and that they are closer.
nightlife_accessA measure, on a 0 to 5 scale, of how easy it is to get to nightlife from this location. Higher values indicate that there are more reachable nightlife, and that they are closer. Nightlife includes bars, pubs, comedy clubs, and night clubs.
park_accessA measure, on a 0 to 5 scale, of how easy it is to get to parks from this location. Higher values indicate that there are more reachable parks, and that they are closer.
park_access_weighted_by_areaA measure, on a 0 to 5 scale, of how easy it is to get to parks from this location, weighted by their area. Higher values indicate that there are more reachable parks, that they are closer, and that that they are larger in area.
pedestrian_oriented_street_accessA measure, on a 0 to 5 scale, of how easy it is to get to pedestrian-oriented commercial streets from this location. Higher values indicate that there are more reachable commercial streets, that they are closer, and that they have more shops and services on them.
rapid_transit_service_accessA measure, on a 0 to 5 scale, of how easy it is to get to rapid transit stations from this location, weighted by how frequent their service is. Higher values indicate that there are more reachable stations, that they are closer, and that service frequency is higher.
restaurant_accessA measure, on a 0 to 5 scale, of how easy it is to get to restaurants from this location. Higher values indicate that there are more reachable restaurants, and that they are closer.
specialty_grocery_store_accessA measure, on a 0 to 5 scale, of how easy it is to get to specialty grocery stores from this location. Higher values indicate that there are more reachable specialty grocery stores, and that they are closer.
sports_facility_accessA measure, on a 0 to 5 scale, of how easy it is to get to sports facilities from this location. Higher values indicate that there are more reachable sports facilities, and that they are closer. Sports facilities include soccer fields, running tracks, baseball diamonds, ice rinks, and so forth.
train_service_accessA measure, on a 0 to 5 scale, of how easy it is to get to train stations from this location, weighted by how frequent their service is. Higher values indicate that there are more reachable stations, that they are closer, and that service frequency is higher.
unhealthy_restaurant_accessA measure, on a 0 to 5 scale, of how easy it is to get to unhealthy restaurants from this location. Higher values indicate that there are more reachable unhealthy restaurants, and that they are closer.
nearest_bus_stop_proximityA measure, on a 0 to 5 scale, of how close the nearest bus stop is. Higher values indicate that it is closer.
nearest_coffee_shop_proximityA measure, on a 0 to 5 scale, of how close the nearest coffee shop is. Higher values indicate that it is closer.
nearest_clothing_and_accessory_store_proximityA measure, on a 0 to 5 scale, of how close the nearest clothing and accessory store is. Higher values indicate that it is closer.
nearest_fitness_establishment_proximityA measure, on a 0 to 5 scale, of how close the nearest fitness establishment is. Higher values indicate that it is closer.
nearest_general_grocery_store_proximityA measure, on a 0 to 5 scale, of how close the nearest general grocery store is. Higher values indicate that it is closer. General grocery stores include supermarkets and other stores that sell a wide range of foods.
nearest_healthy_restaurant_proximityA measure, on a 0 to 5 scale, of how close the nearest healthy restaurant is. Higher values indicate that it is closer.
nearest_highway_proximityA measure, on a 0 to 5 scale, of how close the nearest highway entrance is. Higher values indicate that it is closer.
nearest_nightlife_proximityA measure, on a 0 to 5 scale, of how close the nearest nightlife establishment is. Higher values indicate that it is closer.
nearest_park_proximityA measure, on a 0 to 5 scale, of how close the nearest park is. Higher values indicate that it is closer.
nearest_pharmacy_proximityA measure, on a 0 to 5 scale, of how close the nearest pharmacy is. Higher values indicate that it is closer.
nearest_rapid_transit_station_proximityA measure, on a 0 to 5 scale, of how close the nearest rapid transit station is. Higher values indicate that it is closer.
nearest_restaurant_proximityA measure, on a 0 to 5 scale, of how close the nearest restaurant is. Higher values indicate that it is closer.
nearest_sports_facility_proximityA measure, on a 0 to 5 scale, of how close the nearest sports facility is. Higher values indicate that it is closer.
nearest_train_station_proximityA measure, on a 0 to 5 scale, of how close the nearest train station is. Higher values indicate that it is closer.
nearest_unhealthy_restaurant_proximityA measure, on a 0 to 5 scale, of how close the nearest unhealthy restaurant is. Higher values indicate that it is closer.
nearest_bicycle_share_station_proximityA measure, on a 0 to 5 scale, of how close the nearest bicycle share station is. Higher values indicate that it is closer.
airport_noiseA measure, on a 0 to 5 scale, of how much noise there is from airports at this location.
interchange_noiseA measure, on a 0 to 5 scale, of how much noise there is from highway interchanges at this location.
railway_noiseA measure, on a 0 to 5 scale, of how much noise there is from railways at this location.
traffic_noiseA measure, on a 0 to 5 scale, of how much noise there is from traffic at this location.
terrain_steepnessA measure, on a 0 to 5 scale, of how steep the terrain is within a 1 km radius.
street_steepnessA measure, on a 0 to 5 scale, of how steep the street of this location is.
intersection_densityA measure, on a 0 to 5 scale, of how many street intersections there are per unit of area. Higher values indicate a higher density of intersections, and conversely, smaller blocks.
local_street_proportionA measure, on a 0 to 5 scale, of the proportion of streets within 1 km that are local, as opposed to being highways or arteries.
infrastructure_unpleasant_for_pedestriansA measure, on a 0 to 5 scale, of how much infrastructure there is nearby that is unpleasant for pedestrians. This includes highways and railways.

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