Skip to content

Demographics

Stable
Available in the US and Canada

Information about the kinds of people who live near a specific location can be retrieved using the v1/demographics and v2/demographics endpoints. These endpoints take a lat/lng coordinate pair as inputs, and returns a wide range of demographic variables, organized by categories.

The demographic data returned describes residents who live within a five-minute walk of the given address and can be retrieved using a latitude/longitude request.

All populated areas in Canada and the US (50 states + District of Columbia) are covered.

The /demographics endpoint uses v3 of the Local Logic API. The v1 and v2 versions of this API are no longer supported.

Anyone still using v1 or v2 is strongly encouraged to migrate to v3 to benefit from a variety of security, data and format fixes. Documentation for v1 has been removed, but can be requested at info@locallogic.co.

GET v3/demographics

GET v3/demographics

V3 Data availability

TypeCanadaUSA
Household Income
Individual income·
Commute mode
Household composition
Population age
Housing tenancy
Language knowledge·
Education
Housing type
Family composition·
Mother tongue·

V3 Header Request Parameters

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 Accessing the API → V3 API Authorization.

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

V3 QueryString Request Parameters

ParameterStatusDescription
latrequiredA decimal number between -90 and 90 (Latitude)
lngrequiredA decimal number between -180 and 180 (Longitude)
langoptionalThe language that demographic variable labels will be returned in.
Available: en, fr.
Default: en

V3 NodeJS Example

require('node-fetch')('https://api.locallogic.co/v3/scores?' + new URLSearchParams({
lat: 41.847206,
lng: -87.668825,
lang: 'en',
}), {
method: 'GET',
headers: {
Accept: 'application/json',
Authorization: 'Bearer eyJhbGciOiJ...'
}
})
.then(response => response.json())
.then(body => {
console.log(body)
})
.catch(error => {
console.log(error)
})

V3 Python Example

import requests
response = requests.get(
"https://api.locallogic.co/v3/demographics",
headers={
"Accept": "application/json",
"Authorization": "Bearer eyJhbGciOiJ..."},
params={
"lat": 45.5017,
"lng": -73.5656,
"lang": "en"
}
)
print(response.json())
# See response example below

V3 200 - Response Example

{
"data": {
"type": "demographics",
"attributes": {
"income": {
"label": "Income",
"type": "standalone",
"variables": [
{
"variable": "avg_household_income",
"value": 88555.1858,
"label": "Average household income"
},
{
"variable": "avg_individual_income",
"value": 39706.2035,
"label": "Average individual income"
}
]
},
"commute_mode": {
"label": "Commute mode",
"type": "percent",
"variables": [
{
"variable": "transit",
"value": 0.3483,
"label": "Public transit"
},
{
"variable": "foot",
"value": 0.271,
"label": "Foot"
},
{
"variable": "bicycle",
"value": 0.115,
"label": "Bicycle"
},
{
"variable": "drive",
"value": 0.2339,
"label": "Car"
},
{
"variable": "other",
"value": 0.0318,
"label": "Other"
}
]
}
}
}
}

In the above example of returned data, there are two categories of demographic data (“Income” and “Commute mode”). These categories have the following fields:

label

  • A display label to describe this category

type: which can be either of the following:

  • percent: this category’s variables are directly related; their values are percentages and theoretically should add up to 1.0 (100%). In practice, values may not add to 100% in all cases due to rounding.
  • standalone: this category’s variables are separate values

variables: A list of several variables for the category, each with the following:

  • variable, a programmatic key that will be constant regardless of language
  • value, the actual demographic value
  • label, a language-specific description which can be used for display purposes

In the above example:

The average household income of the surrounding area is $88,555
The average individual income is $39,706
34.8% of people commute by transit
27.1% of people commute by foot
11.5% of people commute by bicycle
23.4% of people commute by car
3.2% of people commute by other modes
The demographic categories and variables returned will vary between supported countries (Canada and the US, as of 2019-09), although they will be consistent within each country. Also, any of the following changes may occur within this version of the API: new categories may be added, variables may change, and variable values may be updated. However, the schema will remain constant.

GET v2/demographics

⚠️ The v2/demographics API is deprecated.
GET v2/demographics

V2 Data Availability

TypeCanadaUSA
Household Income
Individual income·
Commute mode
Household composition
Population age
Housing tenancy
Language knowledge·
Education
Housing type
Family composition·
Mother tongue·

V2 QueryString Request Parameters

ParameterStatusDescription
latrequiredA decimal number between -90 and 90 (Latitude)
lngrequiredA decimal number between -180 and 180 (Longitude)
keyrequiredThe API Key provided for you
langoptionalThe language that demographic variable labels will be returned in.
Available: en, fr.
Default: en

V2 NodeJS Example

require('request')({
method: 'GET',
url: 'https://api.locallogic.co/v2/demographics', // note the v2
qs: {
lat: 45.5017,
lng: -73.5656,
key: 'YOUR_API_KEY'
}
}, function (err, response, body) {
// See response example
})

V2 200 - Response Example

{
"data": {
"type": "Demographics",
"attributes": {
"income": {
"label": "Income",
"type": "standalone",
"variables": [
{
"variable": "avg_household_income",
"value": 88555.1858,
"label": "Average household income"
},
{
"variable": "avg_individual_income",
"value": 39706.2035,
"label": "Average individual income"
}
]
},
"commute_mode": {
"label": "Commute mode",
"type": "percent",
"variables": [
{
"variable": "transit",
"value": 0.3483,
"label": "Public transit"
},
{
"variable": "foot",
"value": 0.271,
"label": "Foot"
},
{
"variable": "bicycle",
"value": 0.115,
"label": "Bicycle"
},
{
"variable": "drive",
"value": 0.2339,
"label": "Car"
},
{
"variable": "other",
"value": 0.0318,
"label": "Other"
}
]
}
}
}
}

In the above example of returned data, there are two categories of demographic data (“Income” and “Commute mode”). These categories have the following fields:

label

  • A display label to describe this category

type: which can be either of the following:

  • percent: this category’s variables are directly related; their values are percentages and theoretically should add up to 1.0 (100%). In practice, values may not add to 100% in all cases due to rounding.
  • standalone: this category’s variables are separate values

variables: A list of several variables for the category, each with the following:

  • variable, a programmatic key that will be constant regardless of language
  • value, the actual demographic value
  • label, a language-specific description which can be used for display purposes

In the above example:

The average household income of the surrounding area is $88,555
The average individual income is $39,706
34.8% of people commute by transit
27.1% of people commute by foot
11.5% of people commute by bicycle
23.4% of people commute by car
3.2% of people commute by other modes
The demographic categories and variables returned will vary between supported countries (Canada and the US, as of 2019-09), although they will be consistent within each country. Also, any of the following changes may occur within this version of the API: new categories may be added, variables may change, and variable values may be updated. However, the schema will remain constant.