Location Scores

StableUS 🇺🇸 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 Score	ScoreName	Description
Pedestrian friendly	`pedestrian_friendly`	Represents how many stores and institutions are nearby and how pleasant it is to walk to them.
Cycling friendly	`cycling_friendly`	Represents 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 friendly	`transit_friendly`	Represents the frequency and level of service of public transit.
Car friendly	`car_friendly`	Represents how well traffic flows, and how easy it is to park.

Services

Location Score	ScoreName	Description
Parks	`parks`	Quantity and area of parks nearby.
Groceries	`groceries`	Distance to closest grocery store and quantity of grocery stores nearby.
Shopping	`shopping`	Quantity and diversity of shops nearby.
Nightlife	`nightlife`	Quantity and diversity of bars nearby.
Restaurants	`restaurants`	Quantity and diversity of restaurants nearby.
Cafes	`cafes`	Quantity and diversity of cafés.
Daycares	`daycares`	Distance to closest daycare school.
Primary Schools	`primary_schools`	Distance to closest elementary school.
High Schools	`high_schools`	Distance to closest high school.

Character

Location Score	ScoreName	Description
Quiet	`quiet`	Level of noise nearby.
Green	`greenery`	Quantity of nearby green spaces and tree canopy coverage.
Historic	`historic`	Presence of heritage buildings and building age in the area.
Vibrant	`vibrant`	Level of street activity nearby.
Wellness	`wellness`	Presence 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.

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 the location scores at 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 score data returned will cover the averaged location scores 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
lat	optional	A decimal number between `-90` and `90`, representing the latitude.
lng	optional	A decimal number between `-180` and `180`, representing the longitude.
geography_ids	optional*	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_levels	optional	A 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`
include	optional	A list `ScoreNames` to return, ex. `car_friendly,pedestrian_friendly`. If no names are provided, all scores included in your agreement will be returned.
language	optional	String value representing the two letter ISO 361-1 language code to return the scores in, ex. `fr` Available: `en` and `fr`
location_scores_rounding	optional	The 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.
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/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)
})

import requests

response = requests.get(
  "https://api.locallogic.co/v3/scores",
  headers={
    "Accept": "application/json",
    "Authorization": "Bearer eyJhbGciOiJ..."},
  params={
    "lat": 43.593611,
    "lng": -79.536194,
    "geography_ids": "g30_f25dv0me",
    "geography_levels": "10,20,30",
    "include": "transit_friendly,quiet",
    "language": "en",
  }
)

print(response.json())

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:

SDK	Description
Local Content SDK	Retrieves the scores for a given location for use in the grouped POI categories within the SDK.
Local Profiles SDK	Retrieves all of the available Transportation, Services, and Character related scores available for the given neighborhood.
NeighborhoodHighlights SDK	Retrieves the scores for the neighborhood in order to calculate the highlights (top scores) of the neighborhood.
NeighborhoodCharacteristics SDK	Retrieves 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"
}

Description​

Score types​

Transportation​

Services​

Character​

GET v3/scores​

Header​

QueryString​

Usage examples​

Response example​

SDK Implementations​

Error codes​