sql-paises-estados-cidades
A MIT-licensed SQL dataset containing comprehensive geographic reference data for Brazil (states, cities, municipalities with IBGE codes) and worldwide countries (with BACEN/trade codes and DDI). Last updated February 2025; primarily PL/SQL with multi-DBMS support. Suitable for Brazilian business applications requiring authoritative location hierarchies and regulatory compliance codes.
Key facts
Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.
| Field | Value |
|---|---|
| Repository | chinnonsantos/sql-paises-estados-cidades |
| Owner | chinnonsantos |
| Primary language | PLSQL |
| License | MIT — OSI-approved |
| Stars | 918 |
| Forks | 305 |
| Open issues | 1 |
| Latest release | v.1.1.0 (2016-04-29) |
| Last updated | 2025-02-25 |
| Source | https://github.com/chinnonsantos/sql-paises-estados-cidades |
What sql-paises-estados-cidades is
PL/SQL-based relational dataset providing three core tables (país, estado, cidade) with geographic identifiers (IBGE municipality codes, BACEN country codes, DDI international dialing codes, latitude/longitude for Brazilian cities, TOM codes for SEFAZ/RFB compliance). Supports PostgreSQL, MySQL, and other SQL dialects via separate script files; includes Docker/PostgreSQL validation harness. Known data integrity issues documented (9 Brazilian municipality codes with invalid check digits; 6 BACEN country codes with invalid control digits).
Get the sql-paises-estados-cidades source
Clone the repository and explore it locally.
git clone https://github.com/chinnonsantos/sql-paises-estados-cidades.gitcd sql-paises-estados-cidades# follow the project's README for install & configurationNeed it deployed, integrated, or customized instead? DEV.co ships production installs.
Best use cases
Implementation considerations
- Import script into target DBMS (PostgreSQL, MySQL, SQL Server, etc.); separate folders provided. Test import using Docker/PostgreSQL harness if available; validate row counts and check digit anomalies against documentation.
- Decide how to handle 9 Brazilian + 6 foreign BACEN records with invalid check digits: patch locally, add validation flag column, or flag in application logic. Document decision for compliance audits.
- IBGE municipality codes are 7-digit UUNNNND format (state code + order + check digit mod-10); validate incoming municipal IDs against this schema before joining to city table.
- Latitude/longitude for Brazilian cities are available; verify accuracy/recency if used for high-precision geolocation (e.g., precise delivery routing).
- DDI (international dialing) codes for countries are marked 'em atualização' (in update) in README; do not rely on completeness for all nations without verification.
When to avoid it — and what to weigh
- Real-time Country/Currency Data Required — Dataset is a static snapshot. Last release v1.1.0 from April 2016; country lists do not reflect recent geopolitical changes (e.g., Montenegro, Serbia validation issues documented). Requires manual updates for new nations or regulatory reclassifications.
- Non-Brazilian Geographic Scope — README explicitly states future foreign state/city data remains 'em breve' (coming soon). If you need hierarchical location data outside Brazil + basic country reference, this is incomplete.
- High-Assurance Data Quality Without Validation — 9 documented Brazilian IBGE codes and 6 BACEN codes have known invalid check digits. Project acknowledges these; you must either patch, validate at import, or accept silent data quality gaps in edge cases.
- Frequent Regulatory/Geographic Updates — Brazilian municipal boundaries, area codes (DDD), and BACEN codes change slowly but do occur. Project maintenance is passive (last PR ~February 2025); no SLA or automated sync to official IBGE/BACEN feeds.
License & commercial use
MIT License (permissive). Allows commercial use, modification, and distribution provided original copyright notice and license text are retained. No liability. Well-established OSI license; safe for proprietary and open-source projects.
MIT is a permissive, OSI-approved license broadly compatible with commercial use. No royalties or commercial restrictions. Retain license header in any distributed derivative. Recommended: review your legal terms for data licensing separately (the SQL dataset itself is licensed MIT, but IBGE/BACEN source data may have separate terms; project README cites official sources—verify those terms if you redistribute).
DEV.co evaluation signals
Editorial assessment — not user reviews. Directional, with an explicit confidence level.
| Signal | Assessment |
|---|---|
| Maintenance | Moderate |
| Documentation | Adequate |
| License clarity | Clear |
| Deployment complexity | Low |
| DEV.co fit | Good |
| Assessment confidence | High |
No sensitive data (geographic reference only); no authentication, encryption, or network exposure required. SQL injection risk exists if municipal/country IDs from user input are not parameterized in queries—apply standard prepared statement practices. Data itself poses no confidentiality concern. Import into isolated environment if handling production data pipelines.
Alternatives to consider
IBGE Official APIs / Geolocation Services
IBGE provides real-time APIs for municipalities, states, and boundaries. Use if you need live data, automatic updates, and Brazilian regulatory alignment. Trade-off: API latency vs. local database query speed.
MaxMind GeoIP / Geonames
Global geographic datasets with city/country hierarchies. Better for non-Brazil scope or multi-country apps. Not specialized for Brazilian tax/banking codes (BACEN, TOM, IBGE).
Custom REST/GraphQL Geolocation API
If you need lightweight, versioned, and audit-tracked lookups, build a thin API layer over this dataset or refresh regularly. Adds operational overhead but enables flexible governance and caching.
Build on sql-paises-estados-cidades with DEV.co software developers
Import this MIT-licensed SQL dataset into your database for instant access to IBGE municipality codes, BACEN country identifiers, and SEFAZ tax codes. Test with our Docker/PostgreSQL harness, then deploy to your DBMS. Review known data anomalies and plan your update cadence.
Talk to DEV.coRelated open-source tools
Surfaced by semantic similarity across the DEV.co open-source index.
Related on DEV.co
Explore the category and the services that help you build with it.
sql-paises-estados-cidades FAQ
Can I use this for a SaaS product serving multiple countries?
How often should I refresh this dataset?
What do I do about the 9 municipalities and 6 countries with invalid check digits?
Does this replace my need for a formal address database (CEP lookup)?
Work with a software development agency
From first prototype to production, DEV.co delivers software development services around tools like sql-paises-estados-cidades. Our software development agency staffs experienced software developers and web developers for custom software development, web development, integrations, and ongoing support across open-source databases and beyond.
Ready to integrate authoritative Brazilian geographic reference data?
Import this MIT-licensed SQL dataset into your database for instant access to IBGE municipality codes, BACEN country identifiers, and SEFAZ tax codes. Test with our Docker/PostgreSQL harness, then deploy to your DBMS. Review known data anomalies and plan your update cadence.