# Colombian Postal Codes Directory (codigospostal.co) - LLM Crawling Guide

## Site Overview

**Website**: https://codigospostal.co
**Purpose**: Searchable directory of Colombian postal codes with geographic boundaries, administrative divisions, and neighborhood information
**Language**: Spanish
**Content Type**: Geographic reference data, postal code lookup, location discovery
**Target Users**: Locals, businesses, and postal services requiring accurate Colombian postal code information

## Core Data Model

### Primary Entities

1. **Departments (Departamentos)**
   - Colombia's first-level administrative divisions (32 total)
   - Contain municipalities and localities
   - Each has a unique department code (DANE code)
   - Examples: Antioquia, Bogotá D.C., Valle del Cauca

2. **Municipalities (Municipios)**
   - Colombia's second-level administrative divisions
   - Contained within departments
   - Each municipality contains multiple postal codes and neighborhoods (barrios/veredas)
   - Examples: Medellín (in Antioquia), Bogotá (in Bogotá D.C.)

3. **Postal Codes (Códigos Postales)**
   - 6-digit numeric identifiers for geographic areas
   - Format: XX-YYYY where first 2 digits = department postal prefix, middle 2 = zone, last 2 = district
   - Urban postal codes typically end with 0-1
   - Rural postal codes typically end with 7-8
   - Example: 050001 (Medellín urban), 050007 (rural area in Antioquia)

4. **Neighborhoods/Barrios (Barrios/Veredas)**
   - Named localities within municipalities
   - Multiple barrios typically served by a single postal code
   - Urban neighborhoods (barrios) and rural areas (veredas)
   - Example: Alcázares Norte, Centro, La Francia (all in Medellín)

5. **Localities (Localidades)**
   - Named populated places and settlements
   - Indexed alphabetically for browsing
   - Can be neighborhoods, rural settlements, or geographic features

### Data Sources

- **Official Colombian Postal Code Shapefiles**: Precise geographical boundaries from the national postal service
- **Municipality and Department Data**: DANE (Departamento Administrativo Nacional de Estadística) administrative divisions
- **Neighborhood Details**: Comprehensive barrio/vereda data with precise coordinates and boundaries

## URL Structure and Taxonomy

### Homepage and Navigation
```
https://codigospostal.co/              - Main homepage with search and navigation
https://codigospostal.co/index.html    - Site homepage
```

### Department Pages
```
https://codigospostal.co/departamento/{department_slug}/
Examples:
- /departamento/ant/                   - Antioquia
- /departamento/bog/                   - Bogotá D.C.
- /departamento/val/                   - Valle del Cauca
```

**Content**: Department overview, list of municipalities, postal code statistics, interactive map showing department boundaries and postal code zones

### Municipality Pages
```
https://codigospostal.co/departamento/{dept_slug}/{municipality_slug}.html
Examples:
- /departamento/ant/medellin.html      - Medellín (in Antioquia)
- /departamento/bog/bogota.html        - Bogotá (in Bogotá D.C.)
- /departamento/bue/bucaramanga.html   - Bucaramanga (in Santander)
```

**Content**: Municipality information, list of postal codes serving the area, neighborhoods, map with municipal boundaries and postal code divisions, population data

### Postal Code Pages
```
https://codigospostal.co/cp/{postal_code}.html
Examples:
- /cp/050001.html                      - Central Medellín postal code
- /cp/110111.html                      - Central Bogotá postal code
- /cp/050007.html                      - Rural area in Antioquia
```

**Content**:
- Department and municipality for the postal code
- List of neighborhoods (barrios/veredas) served by this postal code
- Urban/rural classification
- Interactive map with precise postal code boundary
- Address format template (e.g., "Calle 10 # 15-30, [Neighborhood]")
- Related postal codes in the same municipality

### Neighborhood/Barrio Pages
```
https://codigospostal.co/barrio/{neighborhood_name}-{postal_code}.html
Examples:
- /barrio/alcazares-norte-111211.html  - Alcázares Norte neighborhood (CP 111211)
- /barrio/centro-050001.html           - Centro neighborhood (CP 050001)
- /barrio/la-francia-050001.html       - La Francia neighborhood (CP 050001)
```

**Content**:
- Neighborhood name and postal code
- Municipality and department
- Precise barrio boundary map with individual manzana (city block) visualization
- Address format templates specific to the neighborhood
- Related neighborhoods in the same municipality
- Links to parent postal code and municipality pages

### Postal Code First Digit Pages
```
https://codigospostal.co/cp/{digit}/
Examples:
- /cp/0/                               - Postal codes starting with 0
- /cp/1/                               - Postal codes starting with 1
- /cp/5/                               - Postal codes starting with 5
```

**Content**: Overview of postal codes with given first digit, associated departments, representative municipalities, statistics

### Alphabetical Locality Pages
```
https://codigospostal.co/localidad/{letter}/
Examples:
- /localidad/a/                        - Localities starting with A
- /localidad/m/                        - Localities starting with M
- /localidad/z/                        - Localities starting with Z
```

**Content**: List of all localities/settlements starting with the given letter, links to their postal codes and municipalities

### Individual Locality Pages
```
https://codigospostal.co/localidad/{letter}/{locality_slug}.html
Examples:
- /localidad/a/abastos.html            - Abastos locality
- /localidad/m/medellin.html           - Medellín locality
```

**Content**: Locality information, postal code(s), municipality, department, interactive map

### Information Pages
```
https://codigospostal.co/acerca.html                - About the site
https://codigospostal.co/contacto.html             - Contact information
https://codigospostal.co/privacidad.html           - Privacy policy
https://codigospostal.co/terminos.html             - Terms of use
https://codigospostal.co/sitemap_index.xml         - XML sitemap index
```

## Data Attributes and Field Descriptions

### Department Attributes
- **Name**: Spanish department name (e.g., "Antioquia")
- **Code**: DANE department code (2 digits)
- **Postal Prefix**: 2-digit postal code prefix used by this department (e.g., "05" for Antioquia)
- **Municipality Count**: Number of municipalities in the department
- **Postal Code Count**: Number of unique postal codes
- **Boundaries**: GeoJSON polygon for geographic visualization

### Municipality Attributes
- **Name**: Spanish municipality name
- **Department**: Parent department
- **DANE Code**: Unique municipality code
- **Postal Codes**: Set of postal codes serving this municipality
- **Population**: Population estimate (if available)
- **Neighborhood Count**: Total number of barrios/veredas
- **Boundaries**: GeoJSON polygon for geographic visualization

### Postal Code Attributes
- **Code**: 6-digit postal code (e.g., "050001")
- **Department**: Department code and name
- **Municipality**: Municipality code and name
- **Neighborhoods**: List of barrios/veredas served by this postal code
- **Classification**: Urban or Rural
- **Geometry**: Precise polygon boundary from official shapefiles
- **Map**: Interactive map with boundaries and labels

### Neighborhood (Barrio) Attributes
- **Name**: Spanish neighborhood name (e.g., "Alcázares Norte")
- **Postal Code**: Serving postal code
- **Municipality**: Parent municipality
- **Department**: Parent department
- **Geometry**: Precise manzana boundaries merged into complete barrio outline
- **Related Neighborhoods**: Other barrios in the same municipality
- **Address Format**: Example: "Calle 10 # 15-30, [Neighborhood Name]"

## Search Functionality

### Search Index (Trie-based)
- **Indexed Terms**: 19,115+ entries including:
  - Postal codes (1,384 unique)
  - Municipalities (1,120+)
  - Neighborhoods/Barrios (9,466 neighborhood names)
  - Departments (32)
  - Localities and alternative names

- **Search Location**: `/static/js/trie_*.js` (split across 34 optimized chunks)

- **Search Method**: Instant prefix matching, returns matching postal codes, neighborhoods, municipalities, and departments

## Technical Implementation Details

### Map Integration
- **Provider**: Google Maps / MapTiler tiles
- **Base Layer**: OpenStreetMap-based map tiles
- **Overlay Data**:
  - Department and municipality boundaries (GeoJSON)
  - Postal code zones (GeoJSON with color coding)
  - Neighborhood/Barrio precise boundaries (GeoJSON)
  - Interactive markers and labels

### Postal Code Spatial Data
- **Source**: Official Colombian postal service shapefiles
- **Format**: GeoJSON for web display
- **Simplification**: Configurable simplification tolerance (default: 0.000001 for high accuracy)
- **Coordinate System**: WGS84 (EPSG:4326)
- **Caching**: Geometry caching for performance optimization

### Content Generation
- **Generator**: Python-based static site generator (`gen.py`)
- **Templates**: Jinja2 templates in `/template/` directory
- **Output Format**: Static HTML (JavaScript-free for accessibility)
- **Generated Site**: ~10,000+ pages (departments, municipalities, postal codes, neighborhoods, localities)

## Administrative Divisions Explained

### Colombian Department Codes to Postal Prefixes
The Colombian postal system uses unique prefixes (not DANE codes). Key examples:
- Amazonas: DANE 01 → Postal Prefix 91
- Antioquia: DANE 02 → Postal Prefix 05
- Bogotá D.C.: DANE 05 → Postal Prefix 11
- Valle del Cauca: DANE 29 → Postal Prefix 76
- Santander: DANE 26 → Postal Prefix 68

(See full mapping in site documentation)

### Postal Code Classification
- **Urban (Urbano)**: Postal codes ending with 0-1, serving city centers and urban neighborhoods
- **Rural (Rural)**: Postal codes ending with 7-8, serving remote areas, rural settlements, and veredas

## Content Patterns and Examples

### Homepage Search
Users can search by:
- Postal code (6 digits, e.g., "050001")
- Neighborhood name (e.g., "Centro", "La Francia")
- Municipality (e.g., "Medellín")
- Department (e.g., "Antioquia")

### Department Page Flow
Homepage → Select Department → Browse Municipalities → View Postal Codes → See Neighborhoods

### Postal Code Lookup Flow
Homepage → Search Postal Code → View Details → See Associated Neighborhoods → View Barrio Pages

### Address Formatting
Each neighborhood/postal code provides address format examples:
- **Format**: [Street Type] [Number] # [Cross] - [Number], [Neighborhood Name]
- **Example**: "Calle 10 # 15-30, Alcázares Norte" (for CP 111211, Bogotá)

## Site Statistics

- **Total Postal Codes**: 3,681 unique 6-digit codes
- **Total Departments**: 32
- **Total Municipalities**: 1,120+
- **Total Neighborhoods**: 9,466+ distinct barrios/veredas
- **Search Index Size**: 19,115+ searchable entries across 34 optimized trie chunks

## Data Accuracy and Sources

- **Postal Codes**: Official Colombian postal service shapefiles with precise geographic boundaries
- **Administrative Divisions**: DANE official administrative division boundaries and codes
- **Neighborhood Data**: Detailed barrio and vereda information from official postal service data
- **Geographic Precision**: High-accuracy GeoJSON boundaries suitable for mapping and spatial analysis

## Access Patterns for LLM Crawlers

### Recommended Crawling Strategy
1. Start from `/index.html` (homepage)
2. Follow navigation to department pages (`/departamento/*/`)
3. Browse municipalities within departments
4. Access postal code pages (`/cp/*.html`)
5. Explore neighborhood pages (`/barrio/*.html`)
6. Index alphabetical locality pages (`/localidad/*/`)

### Respecting Site Resources
- Site is static HTML (lightweight)
- No rate limiting necessary
- Sitemap available at `/sitemap_index.xml`
- All content is public and non-commercial reference data

### Content Extraction Guidelines
- **Title Tag**: Contains primary entity name (postal code, neighborhood, municipality, or department)
- **Description**: Primary entity type and geographic context
- **Body Content**: Administrative information, geography, postal code details, related links
- **Maps**: GeoJSON embedded in pages for boundary visualization

## URLs Not to Crawl

- `/static/` - Static assets (CSS, JavaScript, images)
- `/ads.txt` - Advertising configuration
- `robots.txt` - Crawler instructions
- Cache/temporary files

## Structured Data

Each page includes contextual HTML structured to support LLM understanding:
- Hierarchical navigation breadcrumbs showing: Department → Municipality → Postal Code (or Department → Locality)
- Clear heading hierarchy with `<h1>`, `<h2>`, `<h3>` tags
- Entity-specific information clearly labeled
- Related links grouped by category

## For Continuous Crawling

The site is regenerated periodically with:
- Updated postal code data from official sources
- New or modified neighborhood information
- Enhanced geographic boundaries
- Improved search index

**Last Update**: Continuously maintained with latest official Colombian postal service data

---

**Additional Resources**:
- Full project documentation available in repository
- Data sources: Official Colombian postal service shapefiles, DANE administrative divisions
- Questions or corrections: Contact information available at /contacto.html