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 src="https://cdn.jsdelivr.net/npm/all-spanish-cities/dist/index.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 });

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;
  coat_of_arms: string;
  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;
  coat_of_arms: string;
  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 | null;
  coat_of_arms: string | null;
  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: { ... } }]

Data Sources

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

License

MIT © ByMykel