Skip to main content

Location Scores

Stable
US 🇺🇸 and Canada 🇨🇦

Description​

Our Location Scores assess the quality of transportation, services, and character characteristics of locations, broken up into 18 scores on a scale of 0 to 5, which are doubled to display scores out of 10 in our SDK products.

Our Location Scores can be queried for specific locations, listing, and addresses, using latitude and longitude, or for specific Local Logic geographies using unique geog_ids representing neighborhoods, municipalities, and metro areas (any geography levels up to level 40). The Location Scores at the level of geographies & neighborhoods represent the best estimates for the median population-weighted value for each score.

Score types​

Local Logic provides the following Location Scores, which can be accessed via the v3/scores endpoint documented below.

This PDF describes what the values of 0-10 mean for their respective scores.

info

Not all Location Scores are available in all locations.

When scores are missing from the response, it means that Local Logic has insufficient information about the location to be able to provide those scores.

Transportation​

Location ScoreScoreNameDescription
Pedestrian friendlypedestrian_friendlyRepresents how many stores and institutions are nearby and how pleasant it is to walk to them.
Cycling friendlycycling_friendlyRepresents how suitable the area is for cycling in terms of nearby bicycle infrastructure and calm streets, as well as the number of destinations that can be reached by bicycle.
Transit friendlytransit_friendlyRepresents the frequency and level of service of public transit.
Car friendlycar_friendlyRepresents how well traffic flows, and how easy it is to park.

Services​

Location ScoreScoreNameDescription
ParksparksQuantity and area of parks nearby.
GroceriesgroceriesDistance to closest grocery store and quantity of grocery stores nearby.
ShoppingshoppingQuantity and diversity of shops nearby.
NightlifenightlifeQuantity and diversity of bars nearby.
RestaurantsrestaurantsQuantity and diversity of restaurants nearby.
CafescafesQuantity and diversity of cafés.
DaycaresdaycaresDistance to closest daycare school.
Primary Schoolsprimary_schoolsDistance to closest elementary school.
High Schoolshigh_schoolsDistance to closest high school.

Character​

Location ScoreScoreNameDescription
QuietquietLevel of noise nearby.
GreengreeneryQuantity of nearby green spaces and tree canopy coverage.
HistorichistoricPresence of heritage buildings and building age in the area.
VibrantvibrantLevel of street activity nearby.
WellnesswellnessPresence of healthy POIs (fitness/sports, healthy restaurants/stores & parks) nearby and how pedestrian-friendly the location is.

GET v3/scores​

Location Scores for a specific coordinate point location and neighbourhood, macro neighbourhood, and municipality which contains it, can be retrieved using a latitude/longitude request.

Scores for the latitude/longitude point location are returned as a score out of 5, with a precision to the nearest .5. Scores for the neighbourhood, macro neighbourhood, and municipality geography scores are also returned as a score out of 5, but with a precision to the nearest .1.

GET v3/scores

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 data for residents living within a five minute walk of the coordinate. 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 score 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
latoptionalA decimal number between -90 and 90, representing the latitude.
lngoptionalA decimal number between -180 and 180, representing the longitude.
geography_idsoptional*A comma separated list of geography ids, ex. g30_dpz89rm7 or g30_dpz89rm7,g10_dpz89rm7. If this parameter is provided, the lat and lng parameters are optional. A maximum of 100 values are allowed.
geography_levelsoptionalA list of geography levels to include, ex. 10,30. If no geography levels are provided, no geography scores will be returned.

Available: Neighbourhood: 10
Macro-Neighbourhood or Borough: 20
Municipality: 30
includeoptionalA list ScoreNames to return, ex. car_friendly,pedestrian_friendly. If no names are provided, all scores included in your agreement will be returned.
languageoptionalString value representing the two letter ISO 361-1 language code to return the scores in, ex. fr

Available: en and fr
location_scores_roundingoptionalThe type of rounding to apply to the scores returned under data.location. Either .5 (default) to round at the nearest 0.5, or none, to disable rounding.
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/scores?' + new URLSearchParams({
lat: 41.847206,
lng: -87.668825,
geography_ids: 'g30_f25dv0me',
geography_levels: '10,20,30',
include: 'transit_friendly,quiet',
language: 'en',
}), {
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": "scores",
"location": {
"transit_friendly": {
"value": "4.5",
"text": "Within walking distance of a subway and frequent bus lines"
},
"quiet": { "value": "1.0", "text": "Many sources of noise nearby" }
},
"geographies": [
{
"geog_id": "g30_f25dv0me",
"name": "Westmount",
"geog_level_type": "municipality",
"scores": {
"transit_friendly": {
"value": "4.5",
"text": "Within walking distance of a subway and frequent bus lines"
},
"quiet": {
"value": "2.7",
"text": "Multiple sources of noise nearby"
}
}
},
// Plus other geography score objects
]
},
"meta": {
"message": "Successfully called v3/scores API.",
"type": "LocalLogic.API.Success",
"statusCode": 200
}
}

SDK Implementations​

Scores is used by multiple SDKs:

SDKDescription
Local Content SDKRetrieves the scores for a given location for use in the grouped POI categories within the SDK.
Local Profiles SDKRetrieves all of the available Transportation, Services, and Character related scores available for the given neighborhood.
NeighborhoodHighlights SDKRetrieves the scores for the neighborhood in order to calculate the highlights (top scores) of the neighborhood.
NeighborhoodCharacteristics SDKRetrieves all of the available Transportation, Services, and Character related scores available for the given neighborhood.

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