Features

• 19 Autonomies — All Spanish autonomous communities
• 52 Provinces — Complete province data with autonomy relationships
• 8,131 Cities — Every Spanish municipality
• Flags & Coats of Arms — Visual assets from Wikipedia
• Official INE Codes — Instituto Nacional de Estadística codes
• TypeScript Support — Full type definitions included
• Zero Dependencies — Lightweight and fast

Installation

npm install all-spanish-cities

CDN Usage

<script type="module">
  import { cities } from "https://cdn.jsdelivr.net/npm/all-spanish-cities@2/+esm";

  console.log(cities({ code_province: "28" }).length);
</script>

The ESM build is plain modules, so a page that only needs provinces can point straight at that dataset and download ~5 KB instead of ~730 KB:

<script type="module">
  import { provinces } from "https://cdn.jsdelivr.net/npm/all-spanish-cities@2/dist/esm/standalone/provinces.js";
</script>

Usage

import { autonomies, provinces, cities } from "all-spanish-cities";

// Get all autonomies
const allAutonomies = autonomies();

// Get all cities in Madrid province
const madridCities = cities({ code_province: "28" });

// Search cities by name
const results = cities({ name: "Barcelona" });

// Get province with its autonomy data
const [almeria] = provinces({ name: "Almería", with_autonomy: true });

Smaller Imports

The package root loads all three datasets, because with_provinces, with_cities, with_autonomy and with_province can join across any of them. The city data alone is ~720 KB, which is a lot to ship if you only need a province dropdown.

Each dataset is also published on its own subpath. These accept the same filters minus the with_* relations, and load nothing else:

import { autonomies } from "all-spanish-cities/autonomies";  // ~2 KB
import { provinces } from "all-spanish-cities/provinces";    // ~5 KB
import { cities } from "all-spanish-cities/cities";          // ~720 KB

provinces({ code_autonomy: "01" });  // works
provinces({ with_cities: true });    // not available here - use the root import

Bundled with esbuild, importing provinces from the subpath produces 6 KB against 736 KB from the root.

API

autonomies(filters?)

Returns an array of Spanish autonomous communities.

Filters

| Parameter | Type | Description | |-----------|------|-------------| | code | string \| number | Filter by autonomy code | | name | string | Filter by name (case-insensitive, partial match) | | with_provinces | boolean | Include provinces array | | with_cities | boolean | Include cities array |

Response

interface Autonomy {
  code: string;
  name: string;
  flag: string;              // placeholder URL when has_flag is false
  coat_of_arms: string;      // placeholder URL when has_coat_of_arms is false
  has_flag: boolean;
  has_coat_of_arms: boolean;
  provinces?: Province[];  // when with_provinces: true
  cities?: City[];         // when with_cities: true
}

Example

import { autonomies } from "all-spanish-cities";

// Get all autonomies
autonomies();
// → [{ code: "01", name: "Andalucía", flag: "...", coat_of_arms: "..." }, ...]

// Get Catalonia with its provinces
autonomies({ name: "Cataluña", with_provinces: true });
// → [{ code: "09", name: "Cataluña", ..., provinces: [...] }]

provinces(filters?)

Returns an array of Spanish provinces.

Filters

| Parameter | Type | Description | |-----------|------|-------------| | code | string \| number | Filter by province code | | code_autonomy | string \| number | Filter by autonomy code | | name | string | Filter by name (case-insensitive, partial match) | | with_autonomy | boolean | Include parent autonomy object | | with_cities | boolean | Include cities array |

Response

interface Province {
  code: string;
  name: string;
  code_autonomy: string;
  flag: string;              // placeholder URL when has_flag is false
  coat_of_arms: string;      // placeholder URL when has_coat_of_arms is false
  has_flag: boolean;
  has_coat_of_arms: boolean;
  autonomy?: Autonomy;     // when with_autonomy: true
  cities?: City[];         // when with_cities: true
}

Example

import { provinces } from "all-spanish-cities";

// Get all Andalusian provinces
provinces({ code_autonomy: "01" });
// → [{ code: "04", name: "Almería", ... }, { code: "11", name: "Cádiz", ... }, ...]

// Get Barcelona with its cities
provinces({ name: "Barcelona", with_cities: true });
// → [{ code: "08", name: "Barcelona", ..., cities: [...] }]

cities(filters?)

Returns an array of Spanish cities/municipalities.

Filters

| Parameter | Type | Description | |-----------|------|-------------| | code | string \| number | Filter by city code | | code_autonomy | string \| number | Filter by autonomy code | | code_province | string \| number | Filter by province code | | name | string | Filter by name (case-insensitive, partial match) | | with_autonomy | boolean | Include parent autonomy object | | with_province | boolean | Include parent province object |

Response

interface City {
  code: string;
  name: string;
  code_autonomy: string;
  code_province: string;
  flag: string;              // placeholder URL when has_flag is false
  coat_of_arms: string;      // placeholder URL when has_coat_of_arms is false
  has_flag: boolean;
  has_coat_of_arms: boolean;
  autonomy?: Autonomy;     // when with_autonomy: true
  province?: Province;     // when with_province: true
}

Example

import { cities } from "all-spanish-cities";

// Get all cities named "Valverde"
cities({ name: "Valverde" });
// → [{ code: "...", name: "Valverde de Burguillos", ... }, ...] (25 results)

// Get a specific city with full context
cities({ code: "280796", with_autonomy: true, with_province: true });
// → [{ name: "Madrid", autonomy: { name: "Comunidad de Madrid", ... }, province: { ... } }]

Flags & Coats of Arms

Not every municipality has a known flag or coat of arms. flag and coat_of_arms are always a URL so they can be dropped straight into an <img>, falling back to a neutral placeholder image when nothing is known. Use has_flag and has_coat_of_arms to tell the two apart:

import { cities } from "all-spanish-cities";

const [city] = cities({ code: "410883" });

city.flag;      // → ".../no_flag.svg" (placeholder)
city.has_flag;  // → false

// Render only real flags
cities().filter((city) => city.has_flag);

Data Sources

| Data | Source | |------|--------| | Names & Codes | INE (Instituto Nacional de Estadística) | | Flags & Coats of Arms | Wikipedia |

License

MIT © ByMykel