Location Snapshot

StableOnly available in EnglishUS 🇺🇸 and Canada 🇨🇦

Description

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.

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

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

The polygon query string has been limited to 5000 chars.
The max north/south east/west distance accepted is 0.5 degrees.
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.

Parameter	Status	Description
include	required	Comma separated strings of data to be returned. Accepted values are `demographics`, `measures_all`, `pois_count`, and `scores_all`.
lat	optional	A decimal number between `-90` and `90` (Latitude)
lng	optional	A decimal number between `-180` and `180` (Longitude)
radius	optional	A positive float number (Circle radius)
radius_unit	optional	The unit type of the radius. Available: `meter`, `mile`. Default: `meter`
polygon	optional	List of 2D lng/lat points that define a 2D polygon, using the WKT representation

Usage examples

NodeJS
Python

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

import requests

response = requests.get(
"https://api.locallogic.co/v3/data",
headers={
    "Accept": "application/json",
    "Authorization": "Bearer eyJhbGciOiJ..."},
params={
    "lat": 43.593611,
    "lng": -79.536194,
    "include": "demographics,scores_all,measures_all,pois_count"
}
)

print(response.json())
# See response example below

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:

Measure	Description
bus_service_access	A 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_access	A 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_access	A 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_access	A 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_access	A 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_access	A 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_access	A 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_access	A 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_access	A 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_access	A 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_access	A 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_access	A 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_area	A 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_access	A 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_access	A 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_access	A 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_access	A 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_access	A 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_access	A 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_access	A 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_proximity	A 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_proximity	A 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_proximity	A 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_proximity	A 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_proximity	A 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_proximity	A measure, on a 0 to 5 scale, of how close the nearest healthy restaurant is. Higher values indicate that it is closer.
nearest_highway_proximity	A measure, on a 0 to 5 scale, of how close the nearest highway entrance is. Higher values indicate that it is closer.
nearest_nightlife_proximity	A measure, on a 0 to 5 scale, of how close the nearest nightlife establishment is. Higher values indicate that it is closer.
nearest_park_proximity	A measure, on a 0 to 5 scale, of how close the nearest park is. Higher values indicate that it is closer.
nearest_pharmacy_proximity	A 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_proximity	A 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_proximity	A measure, on a 0 to 5 scale, of how close the nearest restaurant is. Higher values indicate that it is closer.
nearest_sports_facility_proximity	A 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_proximity	A 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_proximity	A 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_proximity	A measure, on a 0 to 5 scale, of how close the nearest bicycle share station is. Higher values indicate that it is closer.
airport_noise	A measure, on a 0 to 5 scale, of how much noise there is from airports at this location.
interchange_noise	A measure, on a 0 to 5 scale, of how much noise there is from highway interchanges at this location.
railway_noise	A measure, on a 0 to 5 scale, of how much noise there is from railways at this location.
traffic_noise	A measure, on a 0 to 5 scale, of how much noise there is from traffic at this location.
terrain_steepness	A measure, on a 0 to 5 scale, of how steep the terrain is within a 1 km radius.
street_steepness	A measure, on a 0 to 5 scale, of how steep the street of this location is.
intersection_density	A 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_proportion	A 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_pedestrians	A 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"
}

Description​

GET v3/data​

Header​

QueryString​

Usage examples​

Response example​

Local Logic Measures​

Error codes​