Demographics

StableEnglish and FrenchUS 🇺🇸 and Canada 🇨🇦

Description

Information about the population living around a given location or in a defined area can be retrieved using the v3/demographics endpoint.

warning

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 support@locallogic.co.

Data sources

Country	Source
Canada	Census 2021
USA	American Community Survey 2021

Data availability

Type	Canada	USA
Household Income	✅	✅
Individual income	✅	❌
Commute mode	✅	✅
Household composition	✅	✅
Population age	✅	✅
Housing tenancy	✅	✅
Language knowledge	✅	❌
Education	✅	✅
Housing type	✅	✅
Mother tongue	✅	❌
Employment status	❌	✅
Children per Household	✅	❌

GET v3/demographics

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.

GET v3/demographics

Header

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

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.

Output Attributes and Sub-Variables

Canada

Attribute	Variable	Type	Description
commute_mode			Commute mode
commute_mode	bicycle	percent	Bicycle
commute_mode	drive	percent	Car
commute_mode	foot	percent	Foot
commute_mode	other	percent	Other
commute_mode	transit	percent	Public transit
education_level			Highest level of education achieved
education_level	bachelor_degree	percent	Bachelor degree
education_level	college_certificate	percent	College certificate
education_level	high_school	percent	High school
education_level	no_high_school	percent	Did not graduate high school
education_level	post_graduate_degree	percent	Post graduate degree
education_level	trade_certificate	percent	Trade certificate
education_level	university_certificate	percent	University certificate
household_children			Number of children per household
household_children	avg_children_per_household	average	Average number of children per household
household_composition		Household composition
household_composition	multi_family	percent	Multi family
household_composition	multi_person	percent	Multi person
household_composition	single_family	percent	Single family
household_composition	single_person	percent	Single person
housing_tenancy			Owners vs Renters
housing_tenancy	owners	percent	Owners
housing_tenancy	renters	percent	Renters
housing_type			Housing type
housing_type	apartment_1_to_4_floors	percent	Apartment 1-4 floors
housing_type	apartment_5_plus_floors	percent	Apartment 5 or more floors
housing_type	duplex	percent	Duplex
housing_type	row_houses	percent	Row houses
housing_type	semi_detached	percent	Semi detached
housing_type	single_detached	percent	Single detached
income			Income
income	avg_household_income	standalone	Average household income
income	avg_individual_income	standalone	Average individual income
mother_tongue			Mother tongue
mother_tongue	afrikaans	percent	Afrikaans
mother_tongue	albanian	percent	Albanian
mother_tongue	amharic	percent	Amharic
mother_tongue	arabic	percent	Arabic
mother_tongue	armenian	percent	Armenian
mother_tongue	atikamekw	percent	Atikamekw
mother_tongue	bengali	percent	Bengali
mother_tongue	blackfoot	percent	Blackfoot
mother_tongue	chaldean_neo_aramaic	percent	Chaldean Neo Aramaic
mother_tongue	czech	percent	Czech
mother_tongue	dari	percent	Dari
mother_tongue	dutch	percent	Dutch
mother_tongue	english_and_french	percent	English and French
mother_tongue	english_and_non_official_language_s	percent	English and non-official language(s)
mother_tongue	english_french_and_non_official_language_s	percent	English, French and non-official language(s)
mother_tongue	english	percent	English
mother_tongue	french_and_non_official_language_s	percent	French and non-official language(s)
mother_tongue	french	percent	French
mother_tongue	german	percent	German
mother_tongue	greek	percent	Greek
mother_tongue	gujarati	percent	Gujarati
mother_tongue	hindi	percent	Hindi
mother_tongue	ililimowin_moose_cree	percent	Ililimowin Moose Cree
mother_tongue	inu_ayimun_southern_east_cree	percent	Inu Ayimun Southern East Cree
mother_tongue	inuktitut	percent	Inuktitut
mother_tongue	iranian_persian	percent	Iranian Persian
mother_tongue	italian	percent	Italian
mother_tongue	iyiyiw_ayimiwin_northern_east_cree	percent	Iyiyiw Ayimiwin Northern East Cree
mother_tongue	japanese	percent	Japanese
mother_tongue	korean	percent	Korean
mother_tongue	low_german_nos	percent	Low German Nos
mother_tongue	malayalam	percent	Malayalam
mother_tongue	mandarin	percent	Mandarin
mother_tongue	ndebele	percent	Ndebele
mother_tongue	nehinawewin_swampy_cree	percent	Nehinawewin Swampy Cree
mother_tongue	nehiyawewin_plains_cree	percent	Nehiyawewin Plains Cree
mother_tongue	niger_congo_languages	percent	Niger Congo Languages
mother_tongue	nihithawiwin_woods_cree	percent	Nihithawiwin Woods Cree
mother_tongue	oneida	percent	Oneida
mother_tongue	oriya_nos	percent	Oriya Nos
mother_tongue	oromo	percent	Oromo
mother_tongue	pennsylvania_german	percent	Pennsylvania German
mother_tongue	plautdietsch	percent	Plautdietsch
mother_tongue	polish	percent	Polish
mother_tongue	portuguese	percent	Portuguese
mother_tongue	portuguese	percent	Portuguese
mother_tongue	punjabi_panjabi	percent	Punjabi Panjabi
mother_tongue	romanian	percent	Romanian
mother_tongue	russian	percent	Russian
mother_tongue	somali	percent	Somali
mother_tongue	spanish	percent	Spanish
mother_tongue	swiss_german	percent	Swiss German
mother_tongue	tagalog_pilipino_filipino	percent	Tagalog Pilipino Filipino
mother_tongue	telugu	percent	Telugu
mother_tongue	tlicho_dogrib	percent	Tlicho Dogrib
mother_tongue	ukrainian	percent	Ukrainian
mother_tongue	urdu	percent	Urdu
mother_tongue	vietnamese	percent	Vietnamese
mother_tongue	yue_cantonese	percent	Yue Cantonese
official_language_knowledge			Official language knowledge
official_language_knowledge	en_and_fr	percent	English and French
official_language_knowledge	en_only	percent	English only
official_language_knowledge	fr_only	percent	French only
official_language_knowledge	other	percent	Other
population_age			Population age
population_age	0_to_4	percent	0 to 4
population_age	5_to_9	percent	5 to 9
population_age	10_to_14	percent	10 to 14
population_age	15_to_19	percent	15 to 19
population_age	20_to_34	percent	20 to 34
population_age	35_to_49	percent	35 to 49
population_age	50_to_64	percent	50 to 64
population_age	65_to_79	percent	65 to 79
population_age	80_plus	percent	80 and over
population_total			Total
population_total	total_individuals	standalone	Total individuals

USA

Attribute	Variable	Type	Description
commute_mode			Commute mode
commute_mode	cmtr_cycle	percent	Bike
commute_mode	cmtr_drive	percent	Drive
commute_mode	cmtr_foot	percent	Foot
commute_mode	cmtr_none	percent	None
commute_mode	cmtr_other	percent	Other
commute_mode	cmtr_transt	percent	Transit
education_level			Highest level of education achieved
education_level	ed_bach_deg	percent	Bachelor degree
education_level	ed_collg_dip	percent	College Diploma
education_level	ed_high_sch	percent	High school
education_level	ed_no_high_sc	percent	Did not graduate high school
education_level	ed_post_grad	percent	Post graduate degree
education_level	ed_post_sec	percent	Post secondary degree
employment_status			Employment status
employment_status	emplyd_no	percent	Unemployed
employment_status	emplyd_yes	percent	Employed
household_children			Number of children per household
household_children	home_kids	percent	With kids
household_children	home_no_kids	percent	Without kids
household_composition			Household composition
household_composition	home_1_ppl	percent	1 person
household_composition	home_2_ppl	percent	2 people
household_composition	home_3_ppl	percent	3 people
household_composition	home_4_ppl	percent	4 people
household_composition	home_5_ppl	percent	5 people
household_composition	home_6_plus	percent	6 people or more
housing_type			Housing type
housing_type	apt_attachd	percent	Semi detached
housing_type	apt_bldg_lg	percent	Apartment (large)
housing_type	apt_bldg_sm	percent	Apartment (small)
housing_type	apt_dttachd	percent	Single detached
housing_type	apt_plex	percent	Plex
income_level			Household income brackets
income_level	inc_00_09	percent	$0 to $9,000
income_level	inc_10_19	percent	$10,000 to $19,000
income_level	inc_20_34	percent	$20,000 to $34,000
income_level	inc_35_49	percent	$35,000 to $49,000
income_level	inc_50_74	percent	$50,000 to $74,000
income_level	inc_75_100	percent	$75,000 to $100,000
income_level	inc_100_149	percent	$100,000 to $149,000
income_level	inc_150_200	percent	$150,000 to $200,000
income_level	inc_200_plus	percent	$200,000 or more
income_stats			Income status
income_stats	inc_home	standalone	Household income
income_stats	inc_person	standalone	Individual income
population_age			Population age
population_age	age_00_04	0 to 4	percent
population_age	age_05_09	percent	5 to 9
population_age	age_10_14	percent	10 to 14
population_age	age_15_19	percent	15 to 19
population_age	age_20_24	percent	20 to 24
population_age	age_25_29	percent	25 to 29
population_age	age_30_34	percent	30 to 34
population_age	age_35_39	percent	35 to 39
population_age	age_40_44	percent	40 to 44
population_age	age_45_49	percent	45 to 49
population_age	age_50_54	percent	50 to 54
population_age	age_55_59	percent	55 to 59
population_age	age_60_64	percent	60 to 64
population_age	age_65_69	percent	65 to 69
population_age	age_70_74	percent	70 to 74
population_age	age_75_79	percent	75 to 79
population_age	age_80_84	percent	80 to 84
population_age	age_85_plus	percent	85 and over
population_total			Total
population_total	popn_total	standalone	Total Individuals
property_tenure			Owners vs. renters
property_tenure	prop_owner	percent	Owner
property_tenure	prop_renter	percent	Renter

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

Usage examples

NodeJS

require('node-fetch')('https://api.locallogic.co/v3/demographics?' + new URLSearchParams({
  lat: 41.847206,
  lng: -87.668825,
  radius: 500,
  radius_unit: "meter",
  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)
  })

Python

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

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": "cmtr_transt",
            "value": 0.23562293,
            "label": "Transit"
          },
          {
            "variable": "cmtr_foot",
            "value": 0.011240746,
            "label": "Foot"
          },
          {
            "variable": "cmtr_cycle",
            "value": 0.019079289,
            "label": "Bike"
          },
          {
            "variable": "cmtr_drive",
            "value": 0.60276959,
            "label": "Drive"
          },
          {
            "variable": "cmtr_other",
            "value": 0.016329394,
            "label": "Other"
          },
          {
            "variable": "cmtr_none",
            "value": 0.11495802,
            "label": "None"
          }
        ]
      }
    },
    "meta": {
      "country_code": "US",
      "language": "en",
      "version": "2.0.0"
    },
  },
  "meta": {
    "message": "Successfully called v3/demographics API.",
    "statusCode": 200,
    "type": "LocalLogic.API.Success"
  }
}

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
60.2% of people commute by car
23.5% of people commute by transit
11.4% of people commute by other modes
1.9% of people commute by bicycle
1.1% of people commute by foot

GET v3/demographics/{geog_id}

Fetches demographics data aggregated to the level of Local Logic geographies or neighborhoods, with confidence intervals driven by margin of error in the source data. 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, and data exists for neighborhoods all the way up to metro areas (geography levels 10, 20, 30, and 40).

GET v3/demographics/{geog_id}

Header

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

Parameter	Status	Description
language	optional	The language in which to return the neighborhood names. Accepted values: en, fr Default: en

Output Attributes and Sub-Variables

Canada

Attribute	Variable	Type	Description
commute_mode			Commute mode
commute_mode	commute_mode_total	count	Number of individuals in employed labour force aged 15 years and over
commute_mode	bicycle	percent	Bicycle
commute_mode	drive	percent	Car
commute_mode	foot	percent	Foot
commute_mode	other	percent	Other
commute_mode	transit	percent	Public transit
commute_time			Commute time
commute_time	commute_time_total	count	Number of individuals in employed labour force aged 15 years and over
commute_time	commute_time_00_to_14_minutes	percent	0 to 14 Minutes
commute_time	commute_time_15_to_29_minutes	percent	15 to 29 Minutes
commute_time	commute_time_30_to_44_minutes	percent	30 to 44 Minutes
commute_time	commute_time_45_to_59_minutes	percent	45 to 59 Minutes
commute_time	commute_time_60_plus_minutes	percent	60 Minutes or Longer
education_level			Highest level of education achieved
education_level	education_level_total	count	Number of individuals aged 15 years and over
education_level	bachelor_degree	percent	Bachelor's degree
education_level	college_certificate	percent	College certificate
education_level	doctorate	percent	Doctorate
education_level	high_school	percent	High school
education_level	masters_degree	percent	Master's degree
education_level	medical_degree	percent	Medical degree
education_level	no_high_school	percent	Did not graduate high school
education_level	trade_certificate	percent	Trade certificate
education_level	university_certifcate	percent	University certificate
employment_status			Employment status
employment_status	employment_total	count	Number of individuals in the labour force
employment_status	employment_employed	percent	Employed
employment_status	employment_unemployed	percent	Unemployed
household_composition			Household composition
household_composition	household_size_total_count	count	Number of private households
household_composition	household_size_1_person_percent	percent	1 person
household_composition	household_size_2_people_percent	percent	2 people
household_composition	household_size_3_people_percent	percent	3 people
household_composition	household_size_4_people_percent	percent	4 people
household_composition	household_size_5_plus_people_percent	percent	5 people or more
households			Total Households
households	households_total	count	Total number of private dwellings
households_children			Children in household
households_children	avg_children_per_household	standalone	Average number of children in families with children
households_children	home_households_total	count	Total number of census families in private households
households_children	home_kids	percent	With Children
households_children	home_no_kids	percent	Without Children
housing_bedroom_count			Number of bedrooms per household
housing_bedroom_count	housing_units_total	count	Number of occupied private dwellings
housing_bedroom_count	housing_0_bedroom	percent	Studio
housing_bedroom_count	housing_1_bedroom	percent	1 bedroom
housing_bedroom_count	housing_2_bedrooms	percent	2 bedrooms
housing_bedroom_count	housing_3_bedrooms	percent	3 bedrooms
housing_bedroom_count	housing_4_plus_bedrooms	percent	4 or more bedrooms
housing_construction_year			Housing construction year
housing_construction_year	housing_units_total	count	Number of occupied private dwellings
housing_construction_year	housing_construction_year_before_1961	percent	Before 1961
housing_construction_year	housing_construction_year_1961_to_1980	percent	1961 to 1980
housing_construction_year	housing_construction_year_1981_to_1990	percent	1981 to 1990
housing_construction_year	housing_construction_year_1991_to_2000	percent	1991 to 2000
housing_construction_year	housing_construction_year_2001_to_2010	percent	2001 to 2010
housing_construction_year	housing_construction_year_2011_to_2015	percent	2011 to 2015
housing_construction_year	housing_construction_year_2016_to_2021	percent	2016 to 2021
housing_tenancy			Owners vs. renters
housing_tenancy	prop_occupied_units_total	count	Number of occupied private dwellings
housing_tenancy	owners	percent	Owner
housing_tenancy	renters	percent	Renter
housing_type			Housing type
housing_type	units_total	count	Number of occupied private dwellings
housing_type	apartment_1_to_4_floors	percent	Apartment 1-4 floors
housing_type	apartment_5_plus_floors	percent	Apartment 5 or more floors
housing_type	duplex	percent	Duplex
housing_type	mobile	percent	Mobile
housing_type	row_houses	percent	Row houses
housing_type	semi_detached	percent	Semi detached
housing_type	single_detached	percent	Single detatched
income			Income
income	median_household_income	median	Median household income
income	median_individual_income	median	Median per capita income
income	income_bracket_total	count	Number of private households
income	income_bracket_0_10	percent	$0 to $9,999
income	income_bracket_10_15	percent	$10,000 to $14,999
income	income_bracket_15_20	percent	$15,000 to $19,999
income	income_bracket_20_25	percent	$20,000 to $24,999
income	income_bracket_25_30	percent	$25,000 to $29,999
income	income_bracket_30_35	percent	$30,000 to $34,999
income	income_bracket_35_40	percent	$35,000 to $39,999
income	income_bracket_40_45	percent	$40,000 to $44,999
income	income_bracket_45_50	percent	$45,000 to $49,999
income	income_bracket_50_60	percent	$50,000 to $59,999
income	income_bracket_60_70	percent	$60,000 to $69,999
income	income_bracket_70_80	percent	$70,000 to $79,999
income	income_bracket_80_90	percent	$80,000 to $89,999
income	income_bracket_90_100	percent	$90,000 to $99,999
income	income_bracket_100_125	percent	$100,000 to $124,999
income	income_bracket_125_150	percent	$125,000 to $149,999
income	income_bracket_150_200	percent	$150,000 to $199,999
income	income_bracket_200_plus	percent	$200,000 or more
mother_tongue			Mother tongue
mother_tongue	total_mother_tongue	count	Total Individuals
mother_tongue	afrikaans	percent	Afrikaans
mother_tongue	albanian	percent	Albanian
mother_tongue	amharic	percent	Amharic
mother_tongue	arabic	percent	Arabic
mother_tongue	armenian	percent	Armenian
mother_tongue	atikamekw	percent	Atikamekw
mother_tongue	bengali	percent	Bengali
mother_tongue	blackfoot	percent	Blackfoot
mother_tongue	chaldean_neo_aramaic	percent	Chaldean Neo Aramaic
mother_tongue	czech	percent	Czech
mother_tongue	dari	percent	Dari
mother_tongue	dutch	percent	Dutch
mother_tongue	english_and_french	percent	English and French
mother_tongue	english_and_non_official_languages	percent	English and non-official language(s)
mother_tongue	english_french_and_non_official_languages	percent	English, French and non-official language(s)
mother_tongue	english	percent	English
mother_tongue	french_and_non_official_languages	percent	French and non-official language(s)
mother_tongue	french	percent	French
mother_tongue	german	percent	German
mother_tongue	greek	percent	Greek
mother_tongue	gujarati	percent	Gujarati
mother_tongue	haitian_creole	percent	Haitian Creole
mother_tongue	hindi	percent	Hindi
mother_tongue	ililimowin_moose_cree	percent	Ililimowin Moose Cree
mother_tongue	inu_ayimun_southern_east_cree	percent	Inu Ayimun Southern East Cree
mother_tongue	inuktitut	percent	Inuktitut
mother_tongue	iranian_persian	percent	Iranian Persian
mother_tongue	italian	percent	Italian
mother_tongue	iyiyiw_ayimiwin_northern_east_cree	percent	Iyiyiw Ayimiwin Northern East Cree
mother_tongue	japanese	percent	Japanese
mother_tongue	korean	percent	Korean
mother_tongue	low_german_nos	percent	Low German Nos
mother_tongue	malayalam	percent	Malayalam
mother_tongue	mandarin	percent	Mandarin
mother_tongue	ndebele	percent	Ndebele
mother_tongue	nehinawewin_swampy_cree	percent	Nehinawewin Swampy Cree
mother_tongue	nehiyawewin_plains_cree	percent	Nehiyawewin Plains Cree
mother_tongue	niger_congo_languages	percent	Niger Congo Languages
mother_tongue	nihithawiwin_woods_cree	percent	Nihithawiwin Woods Cree
mother_tongue	oneida	percent	Oneida
mother_tongue	oriya_nos	percent	Oriya Nos
mother_tongue	oromo	percent	Oromo
mother_tongue	pennsylvania_german	percent	Pennsylvania German
mother_tongue	plautdietsch	percent	Plautdietsch
mother_tongue	polish	percent	Polish
mother_tongue	portuguese	percent	Portuguese
mother_tongue	portuguese	percent	Portuguese
mother_tongue	punjabi_panjabi	percent	Punjabi Panjabi
mother_tongue	romanian	percent	Romanian
mother_tongue	russian	percent	Russian
mother_tongue	somali	percent	Somali
mother_tongue	spanish	percent	Spanish
mother_tongue	swiss_german	percent	Swiss German
mother_tongue	tagalog_pilipino_filipino	percent	Tagalog Pilipino Filipino
mother_tongue	telugu	percent	Telugu
mother_tongue	tlicho_dogrib	percent	Tlicho Dogrib
mother_tongue	ukrainian	percent	Ukrainian
mother_tongue	urdu	percent	Urdu
mother_tongue	vietnamese	percent	Vietnamese
mother_tongue	yue_cantonese	percent	Yue Cantonese
official_language_knowledge			Official language knowledge
official_language_knowledge	official_language_knowledge_total	count	Total Individuals
official_language_knowledge	official_language_knoweldge_neither	percent	Neither English nor French
official_language_knowledge	official_language_knowledge_bilingual	percent	English and French
official_language_knowledge	official_language_knowledge_english	percent	English only
official_language_knowledge	official_language_knowledge_french	percent	French only
population_age			Population age
population_age	popn_age_median	median	Median Population Age
population_age	0_to_4	percent	0 to 4
population_age	5_to_9	percent	5 to 9
population_age	10_to_14	percent	10 to 14
population_age	15_to_19	percent	15 to 19
population_age	20_to_24	percent	20 to 24
population_age	25_to_29	percent	25 to 29
population_age	30_to_34	percent	30 to 34
population_age	35_to_39	percent	35 to 39
population_age	40_to_44	percent	40 to 44
population_age	45_to_49	percent	45 to 49
population_age	50_to_54	percent	50 to 54
population_age	55_to_59	percent	55 to 59
population_age	60_to_64	percent	60 to 64
population_age	65_to_69	percent	65 to 69
population_age	70_to_74	percent	70 to 74
population_age	75_to_79	percent	75 to 79
population_age	80_to_84	percent	80 to 84
population_age	85_plus	percent	85 and over
population_total			Total
population_total	total_individuals	count	Total Individuals

USA

Attribute	Variable	Type	Description
commute_mode			Commute mode
commute_mode	cmtr_workers_total	count	Number of workers 16 years and over
commute_mode	cmtr_cycle	percent	Bike
commute_mode	cmtr_drive	percent	Drive
commute_mode	cmtr_foot	percent	Foot
commute_mode	cmtr_none	percent	None
commute_mode	cmtr_other	percent	Other
commute_mode	cmtr_transt	percent	Transit
commute_time			Commute time
commute_time	commute_time_commuting_workers_total	count	Number of workers 16 years and over who did not work from home
commute_time	commute_time_00_to_14_minutes	percent	0 to 14 Minutes
commute_time	commute_time_15_to_29_minutes	percent	15 to 29 Minutes
commute_time	commute_time_30_to_44_minutes	percent	30 to 44 Minutes
commute_time	commute_time_45_to_59_minutes	percent	45 to 59 Minutes
commute_time	commute_time_60_plus_minutes	percent	60 Minutes or Longer
education_level			Highest level of education achieved
education_level	ed_bach_deg	percent	Bachelor's degree
education_level	ed_collg_dip	percent	Degree, certificate, or diploma below bachelor's degree
education_level	ed_high_sch	percent	High School
education_level	ed_masters	percent	Master's degree
education_level	ed_no_high_sc	percent	Did not graduate high school
education_level	ed_phd	percent	PhD
education_level	ed_popn_25_plus	count	Total Individuals 25 years and over
education_level	ed_post_sec	percent	Some college, no degree
education_level	ed_prof_deg	percent	Professional degree
employment_status			Employment status
employment_status	emplyd_no	percent	Unemployed
employment_status	emplyd_popn_16_plus	count	Total Individuals 16 years and over
employment_status	emplyd_yes	percent	Employed
household_composition			Household composition
household_composition	home_households_total	count	Total Households
household_composition	home_1_ppl	percent	1 person
household_composition	home_2_ppl	percent	2 people
household_composition	home_3_ppl	percent	3 people
household_composition	home_4_ppl	percent	4 people
household_composition	home_5_plus	percent	5 people or more
households			Total Households
households	households_total	count	Total Households
households_children			Number of children per household
households_children	home_households_total	count	Total Households
households_children	home_kids	percent	With kids
households_children	home_no_kids	percent	Without kids
housing_bedroom_count			Number of bedrooms per household
housing_bedroom_count	housing_units_total	count	Total Housing Units
housing_bedroom_count	housing_0_bedroom	percent	Studio
housing_bedroom_count	housing_1_bedroom	percent	1 bedroom
housing_bedroom_count	housing_2_bedrooms	percent	2 bedrooms
housing_bedroom_count	housing_3_bedrooms	percent	3 bedrooms
housing_bedroom_count	housing_4_plus_bedrooms	percent	4 or more bedrooms
housing_construction_year			Housing construction year
housing_construction_year	housing_construction_year_median	median	Median Housing Construction Year
housing_construction_year	housing_construction_year_1960_to_1979	percent	1960 to 1979
housing_construction_year	housing_construction_year_1980_to_1989	percent	1980 to 1989
housing_construction_year	housing_construction_year_1990_to_1999	percent	1990 to 1999
housing_construction_year	housing_construction_year_2000_to_2009	percent	2000 to 2009
housing_construction_year	housing_construction_year_2010_to_2019	percent	2010 to 2019
housing_construction_year	housing_construction_year_2020_or_later	percent	2020 or later
housing_construction_year	housing_construction_year_before_1960	percent	Before 1960
housing_construction_year	housing_units_total	count	Total Housing Units
housing_tenancy			Owners vs. renters
housing_tenancy	prop_occupied_units_total	count	Total Occupied Units
housing_tenancy	owners	percent	Owner
housing_tenancy	renters	percent	Renter
housing_type			Housing type
housing_type	apt_units_total	count	Total Housing Units
housing_type	apt_attachd	percent	Semi detached
housing_type	apt_bldg_lg	percent	Apartment (20+ units)
housing_type	apt_bldg_sm	percent	Apartment (5-19 units)
housing_type	apt_dttachd	percent	Single detached
housing_type	apt_mobile	percent	Mobile
housing_type	apt_plex	percent	Multiplex (2-4 units)
income_level			Household income
income_level	inc_households_total	count	Total Households
income_level	inc_00_10	percent	$0 to $10,000
income_level	inc_10_15	percent	$10,000 to $15,0000
income_level	inc_15_20	percent	$15,000 to $20,000
income_level	inc_20_25	percent	$20,000 to $25,000
income_level	inc_25_30	percent	$25,000 to $30,000
income_level	inc_30_35	percent	$30,000 to $35,000
income_level	inc_35_40	percent	$35,000 to $40,000
income_level	inc_40_45	percent	$40,000 to $45,000
income_level	inc_45_50	percent	$45,000 to $50,000
income_level	inc_50_60	percent	$50,000 to $60,000
income_level	inc_60_75	percent	$60,000 to $75,000
income_level	inc_75_100	percent	$75,000 to $100,000
income_level	inc_100_125	percent	$100,000 to $125,000
income_level	inc_125_150	percent	$125,000 to $150,000
income_level	inc_150_200	percent	$150,000 to $200,000
income_level	inc_200_plus	percent	$200,000 or more
income_stats			Income Stats
income_stats	inc_home	median	Median Household Income
income_stats	inc_person	median	Median Per Capita Income
population_age			Population age
population_age	age_median	median	Median Age
population_age	age_popn_total	count	Total Individuals
population_age	age_00_04	percent	0 to 4
population_age	age_05_09	percent	5 to 9
population_age	age_10_14	percent	10 to 14
population_age	age_15_19	percent	15 to 19
population_age	age_20_24	percent	20 to 24
population_age	age_25_29	percent	25 to 29
population_age	age_30_34	percent	30 to 34
population_age	age_35_39	percent	35 to 39
population_age	age_40_44	percent	40 to 44
population_age	age_45_49	percent	45 to 49
population_age	age_50_54	percent	50 to 54
population_age	age_55_59	percent	55 to 59
population_age	age_60_64	percent	60 to 64
population_age	age_65_69	percent	65 to 69
population_age	age_70_74	percent	70 to 74
population_age	age_75_79	percent	75 to 79
population_age	age_80_84	percent	80 to 84
population_age	age_85_plus	percent	85 and over
population_total			Total
population_total	popn_total	count	Total Individuals

Usage examples

NodeJS

require('node-fetch')('https://api.locallogic.co/v3/demographics/g10_dr5rkxmw?' + new URLSearchParams({
  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)
  })

Python

import requests

response = requests.get(
  "https://api.locallogic.co/v3/demographics/g10_dr5rkxmw",
  headers={
    "Accept": "application/json",
    "Authorization": "Bearer eyJhbGciOiJ..."},
  params={
    "language": "en"
  }
)

print(response.json())

Response example

{
  "data": {
    "type": "demographics",
    "attributes": {
      "commute_mode": {
        "variables": [
          {
            "variable": "cmtr_workers_total",
            "type": "count",
            "value": 16792,
            "label": "Number of workers 16 years and over",
            "confidence_interval": {
              "high_estimate": 17861,
              "low_estimate": 15728,
              "confidence_level": 0.9
            }
          },
          {
            "variable": "cmtr_foot",
            "type": "percent",
            "value": 0.105347784659,
            "label": "Foot",
            "confidence_interval": {
              "high_estimate": 0.13018103858980467,
              "low_estimate": 0.08093139590281085,
              "confidence_level": 0.9
            }
          },
          {
            "variable": "cmtr_cycle",
            "type": "percent",
            "value": 0.020366841353,
            "label": "Bike",
            "confidence_interval": {
              "high_estimate": 0.027751310147689376,
              "low_estimate": 0.013101476893758932,
              "confidence_level": 0.9
            }
          },
          {
            "variable": "cmtr_transt",
            "type": "percent",
            "value": 0.537339209147,
            "label": "Transit",
            "confidence_interval": {
              "high_estimate": 0.5784897570271558,
              "low_estimate": 0.4964268699380657,
              "confidence_level": 0.9
            }
          },
          {
            "variable": "cmtr_drive",
            "type": "percent",
            "value": 9.9452120057,
            "label": "Drive",
            "confidence_interval": {
              "high_estimate": 0.12696522153406384,
              "low_estimate": 0.07479752262982372,
              "confidence_level": 0.9
            }
          },
          {
            "variable": "cmtr_other",
            "type": "percent",
            "value": 0,
            "label": "Other",
            "confidence_interval": {
              "high_estimate": 0.0026798475464506905,
              "low_estimate": 0,
              "confidence_level": 0.9
            }
          },
          {
            "variable": "cmtr_none",
            "type": "percent",
            "value": 0.190090519294,
            "label": "None",
            "confidence_interval": {
              "high_estimate": 0.21712720343020486,
              "low_estimate": 0.16335159599809433,
              "confidence_level": 0.9
            }
          }
        ],
        "label": "Commute mode"
      },
      "household_income": {
        "variables": [
          {
            "variable": "inc_25_30",
            "type": "percent",
            "value": 0.015357867284,
            "label": "$25,000 to $30,000",
            "confidence_interval": {
              "high_estimate": 0.022602144305998264,
              "low_estimate": 0.008113590263691683,
              "confidence_level": 0.9
            }
          },
          {
            "variable": "inc_200_plus",
            "type": "percent",
            "value": 0.0208780063749,
            "label": "$200,000 or more",
            "confidence_interval": {
              "high_estimate": 0.23362793393219356,
              "low_estimate": 0.1841495218777166,
              "confidence_level": 0.9
            }
          },
          {
            "variable": "inc_households_total",
            "type": "count",
            "value": 13804,
            "label": "Total Households",
            "confidence_interval": {
              "high_estimate": 14523,
              "low_estimate": 13088,
              "confidence_level": 0.9
            }
          }
        ],
        "label": "Household income"
      },
      "income_stats": {
        "variables": [
          {
            "variable": "inc_home",
            "type": "median",
            "value": 112647,
            "label": "Median Household Income",
            "confidence_interval": {
              "high_estimate": 156106,
              "low_estimate": 69189,
              "confidence_level": 0.9
            }
          },
          {
            "variable": "inc_person",
            "type": "median",
            "value": 68560,
            "label": "Median Per Capita Income",
            "confidence_interval": {
              "high_estimate": 89703,
              "low_estimate": 47418,
              "confidence_level": 0.9
            }
          }
        ],
        "label": "Per capita income"
      },
    },
    "meta": {
      "language": "en",
      "country_code": "US"
    }
  },
  "meta": {
    "message": "Successfully called v3/demographics API.",
    "type": "LocalLogic.API.Success",
    "statusCode": 200
  }
}

In the above example of returned data, there are three categories of demographic data (“Commute mode”, "Household income" and "Per capita income"). 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.
• count: 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
• confidence_interval, which describes a range and the confidence level (as a ratio) for how often we estimate the true value will fall in the given range

In the above example:

9.9% of people commute by car
53.7% of people commute by transit
10.5% of people commute by foot
2.0% of people commute by bicycle
0.0% of people commute by other modes
The median household income is $112,647 (between $69,189 and $156,106 90% of the time)

SDK Implementations

Demographics is used by two SDKs:

SDK	Description
Local Demographics SDK	Retrieves the demographics information near a provided location.
NeighborhoodDemographics SDK	Retrieves the demographics information within a 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"
}