Data & Assets

States, Provinces & Administrative Divisions

The states array contains 5,000+ administrative divisions across every country in the dataset. It is backed by ISO 3166-2 subdivision data, normalized into a consistent set of types such as states, provinces, territories, districts, municipalities, counties, and regions.

Import

import {
  states,
  getStatesByCountry,
  getStateByCode,
  getStatesByType,
} from "arevdata";
import type { State, StateType } from "arevdata";

Data shape

interface State {
  name: string;      // "California"
  code: string;      // "CA" — subdivision code within the country
  country: string;   // "US" — ISO 3166-1 alpha-2 country code
  type: StateType;   // "state" | "province" | "district" | ...
}

type StateType =
  | "state"
  | "province"
  | "territory"
  | "autonomous region"
  | "district"
  | "department"
  | "region"
  | "county"
  | "emirate"
  | "canton"
  | "municipality"
  | "prefecture"
  | "governorate"
  | "parish"
  | "city"
  | "division"
  | "atoll"
  | "island";

Examples

All divisions for a country

import { getStatesByCountry } from "arevdata";

getStatesByCountry("US").length; // 57
getStatesByCountry("CH").length; // 26
getStatesByCountry("JP").length; // 47
getStatesByCountry("MT").length; // 68

Look up a specific division by code

import { getStateByCode } from "arevdata";

getStateByCode("CA", "US");
// { name: "California", code: "CA", country: "US", type: "state" }

getStateByCode("ON", "CA");
// { name: "Ontario", code: "ON", country: "CA", type: "province" }

getStateByCode("ZZ", "US"); // undefined

Filter by normalized division type

import { getStatesByType } from "arevdata";

const provinces = getStatesByType("province");
const cantons = getStatesByType("canton");
const municipalities = getStatesByType("municipality");
const territories = getStatesByType("territory");

Build a country-aware subdivision selector

import { getStatesByCountry } from "arevdata";

function getSubdivisionOptions(countryCode: string) {
  return getStatesByCountry(countryCode).map((division) => ({
    value: division.code,
    label: division.name,
  }));
}

Coverage

Every entry in countries has matching subdivision data.

Representative counts:

Related

• Countries — the country field uses alpha-2 codes from countries
• Cities — the state field in each City can be aligned with entries here