Search by task, endpoint, field, or error.

← Docs

Population

Population and its observation period, by place.

Need a population estimate? Look up the place. Country, state, district, city and postal profiles include a deep.population field with ?deep=true on paid plans. Continent population stays in core on every plan.

deep.population_period sits beside the estimate on place profiles. It is an observation year such as 2024 or a multi-year period such as 2020-2024. Unknown periods stay null. Different places can have different periods. Refreshing a record does not change its observation period.

Where it lives

GET
api.parseapi.com/country/{code}?deep=true
Country, includes population
Explore
Parameters 3
codestring · path · required

ISO 3166-1 alpha-2 or alpha-3, or a country name (germany)

langstring · query · optional

Display language as one BCP 47 tag, such as fr or zh-Hant. Changes supported display labels only; IDs, codes, native names, facts, parsing and deep access stay unchanged. Omit for the original response. Unsupported regions use the supported language base; unsupported languages or scripts use English. Missing labels retain their source value. Accept-Language is not read automatically. Available on the current API contract; frozen 1.0.0 is unchanged.

deepboolean · query · optional

Country profiles, physical geography, statistics, regional conventions, tax references and alternate identifiers. Included on paid plans.

GET
api.parseapi.com/state/{code}?country={iso2}&deep=true
State or province, includes population
Explore
Parameters 4
codestring · path · required

State or province code or name (NC, colorado, ontario)

countrystring · query · optional

ISO2, ISO3, or a country name. Optional when the code or name is globally unique. A collision 404s asking for it.

langstring · query · optional

Display language as one BCP 47 tag, such as fr or zh-Hant. Changes supported display labels only; IDs, codes, native names, facts, parsing and deep access stay unchanged. Omit for the original response. Unsupported regions use the supported language base; unsupported languages or scripts use English. Missing labels retain their source value. Accept-Language is not read automatically. Available on the current API contract; frozen 1.0.0 is unchanged.

deepboolean · query · optional

Population, area, capital, area codes and tax references. Included on paid plans.

GET
api.parseapi.com/district/{code}?deep=true
District, includes population
Explore
Parameters 5
codestring · path · required

District code or name (08031, guilford county, E09000033)

countrystring · query · optional

ISO2, ISO3, or a country name. Optional when the code or name is unique.

statestring · query · optional

ADM1 code or name. Narrows name lookups (washington matches 31 districts). Prefer louisiana over LA, which collides across countries.

langstring · query · optional

Display language as one BCP 47 tag, such as fr or zh-Hant. Changes supported display labels only; IDs, codes, native names, facts, parsing and deep access stay unchanged. Omit for the original response. Unsupported regions use the supported language base; unsupported languages or scripts use English. Missing labels retain their source value. Accept-Language is not read automatically. Available on the current API contract; frozen 1.0.0 is unchanged.

deepboolean · query · optional

Population, area, the seat of government and US county property-tax medians. Included on paid plans.

GET
api.parseapi.com/city/{name}?deep=true
City, includes population
Explore
Parameters 5
namestring · path · required

City name

countrystring · query · optional

ISO country code to disambiguate

statestring · query · optional

State code (bare or ISO-3166-2)

langstring · query · optional

Display language as one BCP 47 tag, such as fr or zh-Hant. Changes supported display labels only; IDs, codes, native names, facts, parsing and deep access stay unchanged. Omit for the original response. Unsupported regions use the supported language base; unsupported languages or scripts use English. Missing labels retain their source value. Accept-Language is not read automatically. Available on the current API contract; frozen 1.0.0 is unchanged.

deepboolean · query · optional

Population, area, elevation and capital status. Included on paid plans.

GET
api.parseapi.com/postal/{code}?country={iso2}&deep=true
Postal / ZIP, includes population
Explore
Parameters 4
codestring · path · required

Postal or ZIP code. Unique codes resolve bare (SW1A 1AA). Use ?country=JP for 100-0001, whose digits also occur in Portugal.

countrystring · query · optional

ISO2, ISO3, or a country name. Optional when the code exists in exactly one covered country. Both five-digit and seven-digit codes can collide.

langstring · query · optional

Display language as one BCP 47 tag, such as fr or zh-Hant. Changes supported display labels only; IDs, codes, native names, facts, parsing and deep access stay unchanged. Omit for the original response. Unsupported regions use the supported language base; unsupported languages or scripts use English. Missing labels retain their source value. Accept-Language is not read automatically. Available on the current API contract; frozen 1.0.0 is unchanged.

deepboolean · query · optional

Population, area, elevation, tax references, nearby postal codes and metropolitan areas. Included on paid plans.

GET
api.parseapi.com/continent/{code}
Continent, includes population
Explore
Parameters 2
codestring · path · required

Two-letter continent code

Values: NA, EU, AF, AS, OC, SA, AN

langstring · query · optional

Display language as one BCP 47 tag, such as fr or zh-Hant. Changes supported display labels only; IDs, codes, native names, facts, parsing and deep access stay unchanged. Omit for the original response. Unsupported regions use the supported language base; unsupported languages or scripts use English. Missing labels retain their source value. Accept-Language is not read automatically. Available on the current API contract; frozen 1.0.0 is unchanged.

Deep examples run with your own key. Check this API’s included units and pricing before running.

SDK quickstart
import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.country("us", { deep: true });
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response
{
  "country": "US",
  "name": "United States",
  "name_local": null,
  "continent": "NA",
  "currency": "USD",
  "currency_name": "United States Dollar",
  "currency_symbol": "$",
  "calling_code": "+1",
  "emoji": "🇺🇸",
  "languages": [
    "en"
  ],
  "timezones": [
    "America/Adak",
    "America/Anchorage",
    "America/Boise",
    "America/Chicago",
    // ... 25 more
  ],
  "deep": {
    "iso3": "USA",
    "numeric": 840,
    "full_name": "United States of America",
    "demonym": "American",
    "capital": "Washington, D.C.",
    "capital_lat": 38.89,
    "capital_lon": -77.05,
    "region": "Americas",
    "subregion": "Northern America",
    "population": 340110988,
    "population_period": null,
    "area": 9629091,
    "land_area": null,
    "water_area": null,
    "coastline": 19924,
    "elevation": 760,
    "lowest_point": {
      "name": "Death Valley",
      "elevation": -86
    },
    "highest_point": {
      "name": "Mount McKinley",
      "elevation": 6190
    },
    "tld": ".us",
    "borders": [
      "CA",
      "MX"
    ],
    "blocs": [
      "G7",
      "NATO",
      "OECD"
    ],
    "week_start": "sunday",
    "units": "imperial",
    "driving_side": "right",
    "plugs": [
      "A",
      "B"
    ],
    "voltage": 120,
    "frequency": 60,
    "emergency": {
      "police": "911",
      "ambulance": "911",
      "fire": "911"
    },
    "postal_format": "#####",
    "postal_regex": "^(?:(\\d{5})(?:[ \\-](\\d{4}))?)$",
    "tax": null,
    "tax_rate": null,
    "tax_id_format": null,
    "tax_id_regex": null,
    "ioc": "USA",
    "fifa": "USA",
    "plate": "USA"
  }
}

Deep examples run with your own key. Check this API’s included units and pricing before running.

SDK quickstart
import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.state("colorado", { deep: true });
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response
{
  "state": "CO",
  "name": "Colorado",
  "deep": {
    "tax": "Sales tax",
    "tax_rate": 2.9
  }
}

Deep examples run with your own key. Check this API’s included units and pricing before running.

SDK quickstart
import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.district("08031", { deep: true });
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response
{
  "district": "08031",
  "name": "Denver County",
  "type": "county",
  "state": "CO",
  "state_name": "Colorado",
  "country": "US",
  "country_name": "United States",
  "latitude": 39.76185,
  "longitude": -104.881105,
  "timezone": "America/Denver",
  "timezones": [
    "America/Denver"
  ],
  "deep": {
    "population": 729019,
    "population_period": null,
    "area": 400.74,
    "land_area": 396.46,
    "water_area": 4.28,
    "seat": "Denver",
    "property_tax": null
  }
}

Deep examples run with your own key. Check this API’s included units and pricing before running.

SDK quickstart
import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.city("charlotte", { deep: true });
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response
{
  "name": "Charlotte",
  "name_local": null,
  "type": "city",
  "state": "NC",
  "state_name": "North Carolina",
  "district": "37119",
  "district_name": "Mecklenburg",
  "country": "US",
  "country_name": "United States",
  "latitude": 35.209045,
  "longitude": -80.83099,
  "timezone": "America/New_York",
  "id": "city_mb8mbqrkz8zb",
  "deep": {
    "capital_of": null,
    "elevation": 209,
    "elevation_ft": 686,
    "population": 943476,
    "population_period": null,
    "area": 813.48,
    "land_area": 808.33,
    "water_area": 5.15
  }
}

Deep examples run with your own key. Check this API’s included units and pricing before running.

SDK quickstart
import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.postal("33139", { country: "US", deep: true });
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response
{
  "postal": "33139",
  "city": "Miami Beach",
  "city_local": null,
  "district": "12086",
  "district_name": "Miami-Dade",
  "district_name_local": null,
  "state": "FL",
  "state_name": "Florida",
  "state_name_local": null,
  "country": "US",
  "country_name": "United States",
  "latitude": 25.779391,
  "longitude": -80.151566,
  "timezone": "America/New_York",
  "deep": {
    "elevation": 6,
    "elevation_ft": 20,
    "population": 33753,
    "population_period": null,
    "area": 15.3,
    "land_area": 7.21,
    "water_area": 8.09,
    "currency": "USD",
    "tax": "Sales tax",
    "tax_rate": null,
    "tax_rate_state": null,
    "tax_rate_county": null,
    "tax_rate_city": null,
    "tax_rate_special": null,
    "property_tax": null,
    "neighbors": [
      "33132",
      "33109",
      "33131",
      "33137",
      "33140",
      "33101",
      "33128",
      "33130"
    ]
  }
}

Run uses the free demo on API 2.0.0. Copied code uses your API key when signed in, or YOUR_API_KEY when signed out.

SDK quickstart
import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.continent("na");
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response
{
  "continent": "NA",
  "name": "North America",
  "region": "Americas",
  "subregion": "Northern America",
  "population": 600000000,
  "area": 24709000,
  "emoji": "🌎"
}

District lists under /state/{code}/districts also carry deep.population when requested on paid plans and available.

Questions? Email