National Boundaries and Addresses API of Lithuania

Access comprehensive data on national boundaries and addresses registered in the Republic of Lithuania. This API provides detailed information and geometries about counties, municipalities, elderships, residential areas, streets, addresses, rooms and parcels.

Key features

1. No extra dependencies: A single Docker image without the need for databases like Postgres or MySQL.

2. Easy Usage: OpenAPI support for quick client and contract generation in your favorite programming language.

3. Advanced Filtering and Searching: Filter by geometries, various attributes, transform geometries to different SRIDs, and more.

4. Frequent Updates: Daily Docker image updates on changes to boundaries or addresses.

5. Infinite horizontal scaling: API can be scaled horizontally without state or extra services.

6. Compact and Efficient: SQLite database with all boundaries, addresses, and geometries under 500 MB.

7. Flexible Deployment: Easily deployable on various infrastructures, supporting containerization and orchestration tools.

8. Completely Open Source and Free: Join our community of contributors and users. The entire project is open-source and free of restrictions..

Self-hosting

Host National Boundaries and Addresses API of Lithuania on your own infrastructure.

Docker Image

Here's an example of its usage with Docker Compose:

services:
  national-boundaries-api:
    image: ghcr.io/govlt/national-boundaries-api:main
    pull_policy: always
    restart: unless-stopped
    ports:
      - "80:80"
    healthcheck:
      test: [ "CMD-SHELL", "wget --no-verbose --tries=1 --spider http://127.0.0.1:80/health || exit 1" ]
      interval: 5s
      timeout: 3s
      start_period: 5s
      retries: 5

Additional docker image environment options:

Environment Variable	Description	Default Value
SENTRY_DSN	The DSN for Sentry, used for error tracking and monitoring. Leave empty if Sentry is not used.
SENTRY_ENVIRONMENT	Specifies the environment for Sentry (e.g., production, staging, development).	production
ROOT_URL	The root URL of the application. Only change if the application is mounted below a specific URL path.
WORKERS	The number of Uvicorn worker processes to run. Adjust based on workload and available resources. If you have a cluster of machines with Kubernetes, Docker Swarm, or another similar system, handle replication at the cluster level and keep a single worker per container.	1

SQLite Database

Optionally, use the SQLite database with all boundaries and addresses directly without running the national-boundaries-api. Download the latest database version here.

Architecture

flowchart TD
    ar["State Enterprise Centre of Registers\n<a href="https://www.registrucentras.lt/p/1187">Address Registry raw data</a>"]-->transform["<a href="https://github.com/govlt/national-boundaries-api/blob/main/create-database.sh">Create SQLite database</a>"]-->|"<a href="https://github.com/govlt/national-boundaries-api/releases/latest/download/boundaries.sqlite">boundaries.sqlite</a>"|docker-image

docker-image["Docker image\n<a href="https://github.com/govlt/national-boundaries-api/pkgs/container/national-boundaries-api">national-boundaries-api</a>"]

Loading

Getting Started Development

To embark on your development journey, follow these simple steps:

• Install Python 3.12+: Download Python
• Install Poetry 1.8+: Download Poetry
• Install SpatialLite 5+: Download SpatialLite
• Install GDAL 3.9+: Download GDAL (Needed only for building the SQLite file on your computer)

Setup

1. Set up a Python virtual environment.
2. Install dependencies with Poetry.
3. Create the database by running create-database.sh or download the database file from this link and place it in the project root directory.

Run the Development API

Execute the following command, replacing SPATIALITE_LIBRARY_PATH with the path to SpatialLite on your computer:

SPATIALITE_LIBRARY_PATH="mod_spatialite.dylib" poetry run python -m uvicorn src.main:app --reload

License

This project is licensed under the MIT License. Data from this API is licensed under CC BY 4.0. For more information, visit Registrų centras.

While preparing the National Boundaries and Addresses API, some changes were made such as changing attribute names to English. For full details, check out the create-database.sh file.

Contributing

Join our community! Your contributions are invaluable. Whether you spot issues or have innovative ideas, feel free to open an issue or submit a pull request. Check out our contribution guidelines for more details.