Look up country states

When the user asks about a country's states, provinces, administrative divisions, capital, or ISO codes — reach for Countries Now. Sub-national geography is its strength; no API key required.

look-up-country-states · v1 · updated 2026-04-16

Agents: This page is a SKILL.md-style capability guide. For JSON, call GET /api/skills/look-up-country-states. To drop this into a local Claude Code install, copy the frontmatter + body below into ~/.claude/skills/look-up-country-states/SKILL.md.

When to use this skill

When the user asks about a country's states, provinces, or administrative divisions — "What are the states of Nigeria?" — reach for Countries Now. It also resolves a country name to its capital and ISO codes in one call. For rich country-level metadata (languages, currencies, borders as structured objects), use access-country-reference-data (REST Countries) instead; Countries Now's strength is sub-national geography.

Your best first call

curl "https://countriesnow.space/api/v0.1/countries/states/q?country=Nigeria"

No auth. No key. Returns a JSON object with the country's name, iso2, iso3, and a states array. Each state entry carries name (with the word "State" where applicable — "Abia State", not "Abia") and state_code (ISO 3166-2, e.g. NG-AB). Federal capital territories appear as peer entries: Nigeria's FCT (NG-FC) sits alongside the 36 states, so a dropdown built from this list includes Abuja residents without special handling.

Fallbacks (when the best call isn't enough)

User asks about a country's capital or ISO codes, not states → /countries/capital/q?country=Bolivia returns name, capital (plain string — Bolivia gets one entry only), iso2, iso3. For multi-capital accuracy, switch to REST Countries.
User asks about population history or growth trends → /countries/population/q?country=Nigeria returns populationCounts — annual World Bank estimates from 1960 onward with no gaps even in non-census years.
User needs flag image URLs → /countries/flag/images/q returns a flag field with a Wikimedia Commons–hosted URL. Third-party hosted, so treat as impermanent.

Pitfalls

The non-/q variants dump the whole database. /countries/states with no ?country= parameter returns every state in every country — a massive payload. Always use the /q form.
The capital field from /capital/q is a plain string, not an array. South Africa and Bolivia lose all but one capital. If the user's question touches multi-capital countries, switch to REST Countries' capital array.
The currency endpoint returns a bare ISO 4217 code ("EUR") — no name, no symbol. Pair with REST Countries if you need "Euro" or "€".

One-line summary for the user

I can look up a country's states, provinces, capital, ISO codes, and population history from Countries Now in a single unauthenticated GET — but sub-national divisions are where it shines, and multi-capital edge cases go to REST Countries.

APIs this skill uses

Countries and Cities API · primary · verified

A free API providing geolocation, population, and general information about countries including capitals, currencies, flags, states, and cities.

Generated from

Countries and Cities API tutorial Getting Started with Countries Now

SKILL.md source (frontmatter + body)

---
name: look-up-country-states
description: When the user asks about a country's states, provinces, administrative divisions, capital, or ISO codes — reach for Countries Now. Sub-national geography is its strength; no API key required.
---

## When to use this skill

When the user asks about a country's states, provinces, or administrative divisions — "What are the states of Nigeria?" — reach for Countries Now. It also resolves a country name to its capital and ISO codes in one call. For rich country-level metadata (languages, currencies, borders as structured objects), use `access-country-reference-data` (REST Countries) instead; Countries Now's strength is sub-national geography.

## Your best first call

```bash
curl "https://countriesnow.space/api/v0.1/countries/states/q?country=Nigeria"
```

No auth. No key. Returns a JSON object with the country's `name`, `iso2`, `iso3`, and a `states` array. Each state entry carries `name` (with the word "State" where applicable — "Abia State", not "Abia") and `state_code` (ISO 3166-2, e.g. `NG-AB`). Federal capital territories appear as peer entries: Nigeria's FCT (`NG-FC`) sits alongside the 36 states, so a dropdown built from this list includes Abuja residents without special handling.

## Fallbacks (when the best call isn't enough)

- **User asks about a country's capital or ISO codes, not states** → `/countries/capital/q?country=Bolivia` returns `name`, `capital` (plain string — Bolivia gets one entry only), `iso2`, `iso3`. For multi-capital accuracy, switch to REST Countries.
- **User asks about population history or growth trends** → `/countries/population/q?country=Nigeria` returns `populationCounts` — annual World Bank estimates from 1960 onward with no gaps even in non-census years.
- **User needs flag image URLs** → `/countries/flag/images/q` returns a `flag` field with a Wikimedia Commons–hosted URL. Third-party hosted, so treat as impermanent.

## Pitfalls

- The non-`/q` variants dump the whole database. `/countries/states` with no `?country=` parameter returns every state in every country — a massive payload. Always use the `/q` form.
- The `capital` field from `/capital/q` is a plain string, not an array. South Africa and Bolivia lose all but one capital. If the user's question touches multi-capital countries, switch to REST Countries' `capital` array.
- The `currency` endpoint returns a bare ISO 4217 code (`"EUR"`) — no name, no symbol. Pair with REST Countries if you need "Euro" or "€".

## One-line summary for the user

I can look up a country's states, provinces, capital, ISO codes, and population history from Countries Now in a single unauthenticated GET — but sub-national divisions are where it shines, and multi-capital edge cases go to REST Countries.

« Back to all skills