Getting Started with Countries Now

← Countries and Cities API

When to use this API

When you need to drill into sub-national geography — states, provinces, or cities within a country — or pull historical population estimates. REST Countries handles country-level identity data better (borders, languages, currencies as rich objects); Countries Now is the right tool when the user asks "what are the states of X" or "how has X's population changed since 1960." It also provides a lightweight endpoint for resolving a country name to its capital and ISO codes in a single unauthenticated call. No API key required.

Listing states and provinces within a country

"What are the states of Nigeria?" The /countries/states/q endpoint returns all first-level administrative divisions with their ISO 3166-2 codes.

curl "https://countriesnow.space/api/v0.1/countries/states/q?country=Nigeria" | head -c 10000

{
  "error": false,
  "msg": "states in Nigeria retrieved",
  "data": {
    "name": "Nigeria",
    "iso3": "NGA",
    "iso2": "NG",
    "states": [
      { "name": "Abia State", "state_code": "NG-AB" },
      { "name": "Adamawa State", "state_code": "NG-AD" },
      { "name": "Bayelsa State", "state_code": "NG-BY" },
      { "name": "Borno State", "state_code": "NG-BO" },
      { "name": "Federal Capital Territory", "state_code": "NG-FC" },
      { "name": "Lagos State", "state_code": "NG-LA" }
      // ... 31 more
    ]
  }
}

Nigeria has 36 states plus the Federal Capital Territory, and the FCT appears inline in the list — code NG-FC — rather than in a separate field. That's the right call: Abuja sits outside all 36 states administratively, so surfacing it as a peer entry means a form built from this list won't silently drop Abuja residents. Note that the name values include the word "State" (e.g., "Abia State", not "Abia") — if you're using these for display, that suffix is already there. The state_code values follow ISO 3166-2 and are stable join keys.

Nigeria has 36 states plus the Federal Capital Territory (where Abuja is located). The states include Abia (NG-AB), Adamawa (NG-AD), Akwa Ibom (NG-AK), Anambra (NG-AN), Bauchi (NG-BA), Bayelsa (NG-BY), Benue (NG-BE), Borno (NG-BO), Cross River (NG-CR), Delta (NG-DE), and 26 others. The Federal Capital Territory (NG-FC) is listed alongside the states.

Fetching a country's annual population estimates

"How has Nigeria's population grown since independence?" The /countries/population/q endpoint returns a populationCounts array with one entry per year, making it usable for plotting growth curves or finding when a country crossed a specific population threshold.

curl "https://countriesnow.space/api/v0.1/countries/population/q?country=Nigeria" | head -c 10000

{
  "error": false,
  "msg": "Nigeria with population",
  "data": {
    "country": "Nigeria",
    "code": "NGA",
    "iso3": "NGA",
    "populationCounts": [
      { "year": 1960, "value": 45138458 },
      { "year": 1961, "value": 46063563 },
      { "year": 1962, "value": 47029822 },
      { "year": 1963, "value": 48032934 },
      { "year": 1964, "value": 49066760 },
      { "year": 1965, "value": 50127921 }
      // ... annual entries continuing to present
    ]
  }
}

Nigeria added roughly a million people per year through the 1960s starting from a 1960 base of 45 million — the growth is evident in the first five entries alone. These are World Bank estimates rather than census readings, so the series has no gaps even in years without an official census; that's why the curve is smooth and you can pick any year without worrying about missing data. The code and iso3 fields both carry the same ISO alpha-3 value, a minor redundancy you can ignore.

Nigeria's population was approximately 45.1 million in 1960, growing to about 50.1 million by 1965. The data is a continuous annual series — let me know a specific year or threshold and I can pull the exact estimate.

Resolving a country name to its capital and ISO codes

"What's the capital of France and what ISO codes does it use?" The /countries/capital/q endpoint is a minimal lookup that returns a country's capital city, ISO alpha-2, and ISO alpha-3 codes together in one call. France is the only probe available for this endpoint — a dull example for a tutorial, but it's what the data gives us. The practical use case is name resolution: if you only have a country name as a string and need the ISO codes to join against another API, this is one unauthenticated GET.

curl "https://countriesnow.space/api/v0.1/countries/capital/q?country=France" | head -c 10000

{
  "error": false,
  "msg": "country and capitals retrieved",
  "data": {
    "name": "France",
    "capital": "Paris",
    "iso2": "FR",
    "iso3": "FRA"
  }
}

The capital field is a plain string, not an array. REST Countries models capitals as an array to handle multi-capital countries cleanly (Bolivia has three); Countries Now collapses them to one. For most countries this doesn't matter, but for South Africa (Pretoria/Cape Town/Bloemfontein) or Bolivia you get one and lose the rest. If geopolitical precision is required, use REST Countries for the capital field; use this endpoint only when you need a fast ISO code lookup alongside a capital.

France's capital is Paris. Its ISO codes are FR (alpha-2) and FRA (alpha-3).

Pitfalls

One-line summary for the user

I can look up a country's first-level administrative divisions with ISO 3166-2 codes, annual population estimates back to 1960, capital city, currency code, and flag image URL from countriesnow.space — no API key required, and the sub-national data (states, cities) is what sets it apart from REST Countries.