https://github.com/ByMykel/spanish-cities
A library that provides data on Spain's autonomies, provinces, and cities, including their codes, names, flags, and coats of arms for seamless integration into your applications.
https://github.com/ByMykel/spanish-cities
autonomy city coat-of-arms flags hacktoberfest province spain
Last synced: 3 days ago
JSON representation
A library that provides data on Spain's autonomies, provinces, and cities, including their codes, names, flags, and coats of arms for seamless integration into your applications.
- Host: GitHub
- URL: https://github.com/ByMykel/spanish-cities
- Owner: ByMykel
- License: mit
- Created: 2023-02-05T12:11:09.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2026-03-11T19:46:36.000Z (4 months ago)
- Last Synced: 2026-05-15T04:51:12.313Z (about 1 month ago)
- Topics: autonomy, city, coat-of-arms, flags, hacktoberfest, province, spain
- Language: Python
- Homepage: https://bymykel.github.io/spanish-cities/
- Size: 1.83 MB
- Stars: 5
- Watchers: 1
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-spain - spanish-cities - cities?style=flat-square&label=%E2%AD%90)](https://github.com/ByMykel/spanish-cities/stargazers) [](https://github.com/ByMykel/spanish-cities/commits/main) [](https://github.com/ByMykel/spanish-cities) [](https://github.com/ByMykel/spanish-cities/blob/main/LICENSE) [](https://www.ine.es/) - Librería Python con datos de autonomías, provincias y ciudades de España con códigos, nombres, banderas y escudos. (Datos Abiertos y Estadísticas / Región de Murcia)
README
all-spanish-cities
A comprehensive library providing data on Spain's autonomies, provinces, and cities — including codes, names, flags, and coats of arms.
Live Demo •
Installation •
Usage •
API •
License
---
## 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
```bash
npm install all-spanish-cities
```
### CDN Usage
```html
```
## Usage
```js
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
```ts
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
```js
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
```ts
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
```js
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
```ts
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
```js
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)](https://www.ine.es/dyngs/INEbase/es/operacion.htm?c=Estadistica_C&cid=1254736177031&menu=ultiDatos&idp=1254734710990) |
| Flags & Coats of Arms | Wikipedia |
## License
[MIT](LICENSE) © [ByMykel](https://github.com/ByMykel)