Demographics

Table of contents

GET v3/demographics
GET v2/demographics

Stable

Available in the US and Canada

Table of contents

GET v3/demographics
GET v2/demographics

Information about the population living around a given location or in a defined area can be retrieved using the v3/demographics endpoint. The data returned describes a wide range of demographic variables, organized by categories. All populated areas in Canada and the US (50 states + District of Columbia) are covered.

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 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 geohashes is 1000.

Warning

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

⚠️ 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 and v2 APIs has been removed, but can be requested at info@locallogic.co.

GET v3/demographics

GET v3/demographics

V3 Data availability

Type	Canada	USA
Household Income	✅	✅
Individual income	✅	·
Commute mode	✅	✅
Household composition	✅	✅
Population age	✅	✅
Housing tenancy	✅	✅
Language knowledge	✅	·
Education	✅	✅
Housing type	✅	✅
Family composition	✅	·
Mother tongue	✅	·
Employment status	.	✅

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.

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`.

V3 QueryString Request Parameters

Parameter	Status	Description
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
lang	optional	The language that demographic variable labels will be returned in. Available: `en`, `fr`. Default: `en`

V3 NodeJS example using `lat`/`lng` parameters

require('node-fetch')('https://api.locallogic.co/v3/demographics?' + 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 using `lat`/`lng` and `radius`/`radius_unit` parameters

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,
        "radius": 500,
        "radius_unit": "meter",
        "lang": "en"
    }
)
print(response.json())
# See response example below

V3 Python example using `polygon` parameter

import requests
response = requests.get(
    "https://api.locallogic.co/v3/demographics",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer eyJhbGciOiJ..."},
    params={
            "polygon": (
                "POLYGON(("
                "-73.599092 45.528410, "
                "-73.596265 45.528433, "
                "-73.599123 45.527344, "
                "-73.599092 45.528410))"
            )
    }
)
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 and only supports querying data by specifying a `lat`/`lng` coordinate.

GET v2/demographics

V2 Data Availability

Type	Canada	USA
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

Parameter	Status	Description
lat	required	A decimal number between `-90` and `90` (Latitude)
lng	required	A decimal number between `-180` and `180` (Longitude)
key	required	The API Key provided for you
lang	optional	The 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"
                    }
                ]
            }
        }
    }
}