{"id":31537635,"url":"https://github.com/nipsysdev/oakality","last_synced_at":"2026-04-10T23:33:43.173Z","repository":{"id":317846615,"uuid":"1068872123","full_name":"nipsysdev/oakality","owner":"nipsysdev","description":"A Deno and Oak-based HTTP server that extracts and serves pmtiles (vector tiles) for localities worldwide. ","archived":false,"fork":false,"pushed_at":"2025-10-03T12:56:42.000Z","size":26,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-03T13:08:21.661Z","etag":null,"topics":["deno","http-server","oak","openstreetmap","osm","pmtiles","protomaps","whosonfirst"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nipsysdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-03T03:28:36.000Z","updated_at":"2025-10-03T12:56:46.000Z","dependencies_parsed_at":"2025-10-03T13:08:25.248Z","dependency_job_id":"5aa376b5-678c-4da6-b3b4-4414cc4feb74","html_url":"https://github.com/nipsysdev/oakality","commit_stats":null,"previous_names":["nipsysdev/oakality"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/nipsysdev/oakality","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nipsysdev%2Foakality","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nipsysdev%2Foakality/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nipsysdev%2Foakality/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nipsysdev%2Foakality/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nipsysdev","download_url":"https://codeload.github.com/nipsysdev/oakality/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nipsysdev%2Foakality/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278283509,"owners_count":25961311,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deno","http-server","oak","openstreetmap","osm","pmtiles","protomaps","whosonfirst"],"created_at":"2025-10-04T08:08:23.271Z","updated_at":"2025-10-04T08:08:25.172Z","avatar_url":"https://github.com/nipsysdev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Oakality - Pmtiles Server for World Localities\n\nOakality is an HTTP server built with Deno and Oak that serves pmtiles (vector\ntiles) for localities (cities, towns, villages) from around the world. It\nextracts and serves pmtiles files based on geographic boundaries from the\nWhosOnFirst admin database.\n\n## Prerequisites\n\nBefore running Oakality, ensure you have the following command-line tools\ninstalled:\n\n- `pmtiles` - For extracting pmtiles files\n  ([Install instructions here](https://docs.protomaps.com/guide/getting-started))\n- `bzip2` - For decompressing the database\n- `find` - For efficient file operations\n\n## Installation\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/nipsysdev/oakality.git\n   cd oakality\n   ```\n\n2. Install Deno if you haven't already:\\\n   https://docs.deno.com/runtime/getting_started/installation/\n\n3. Install dependencies\n   ```bash\n   deno install\n   ```\n\n## Usage\n\n### Starting the Server\n\nRun the following command to start the server:\n\n```bash\ndeno task start\n```\n\nThe server will start on port 8080 (or as configured in `src/constants.ts`).\n\n### First Run\n\nOn the first run, the application will:\n\n1. Download the WhosOnFirst admin database (compressed bzip2)\n2. Decompress the database to SQLite format\n3. Check for existing pmtiles files\n4. Prompt you to extract missing pmtiles files if needed\n\n\u003e Be aware that, by default, all localities from every country available will be\n\u003e queued for extraction.\\\n\u003e Downloading everything will take a significant amount of hours (days\n\u003e potentially!)\n\u003e\n\u003e You can restrict the download of pmtiles to specific countries by setting\n\u003e TARGET_COUNTRIES to an array of country codes in `src/constants.ts`.\n\n## API Endpoints\n\n### Countries\n\n- **GET** `/countries`\n  - Returns a list of all countries with their codes and locality counts\n  - Response format:\n    ```json\n    {\n      \"success\": true,\n      \"data\": [\n        {\n          \"countryCode\": \"BE\",\n          \"countryName\": \"Belgium\",\n          \"localityCount\": 2136\n        }\n      ]\n    }\n    ```\n\n### Localities\n\n- **GET** `/countries/:countryCode/localities`\n  - Returns a paginated list of 20 localities for a specific country\n  - Query parameters:\n    - `q` (optional): Text to search in locality names\n    - `page` (optional): Page number (default: 1)\n  - Response format:\n    ```json\n    {\n      \"success\": true,\n      \"data\": [\n        {\n          \"id\": 101839773,\n          \"name\": \"Brugelette\",\n          \"country\": \"BE\",\n          \"placetype\": \"locality\",\n          \"latitude\": 50.576433,\n          \"longitude\": 3.851975,\n          \"fileSize\": 2928590\n        },\n        {\n          \"id\": 101748097,\n          \"name\": \"Brugge\",\n          \"country\": \"BE\",\n          \"placetype\": \"locality\",\n          \"latitude\": 51.208664,\n          \"longitude\": 3.217718,\n          \"fileSize\": 6773970\n        }\n      ],\n      \"pagination\": {\n        \"total\": 6,\n        \"page\": 1,\n        \"limit\": 20,\n        \"totalPages\": 1\n      }\n    }\n    ```\n\n### Pmtiles Files\n\n- **GET** `/countries/:countryCode/localities/:id/pmtiles`\n  - Serves the pmtiles file for a specific locality\n  - Sets appropriate headers for file download\n  - Returns 404 if the file doesn't exist\n\n## Configuration\n\nConfiguration constants are defined in `src/constants.ts`:\n\n- `PORT`: Server port number (8080)\n- `ASSETS_DIR`: Directory for storing assets (assets)\n- `PMTILES_CMD`: Command-line tool for pmtiles operations (pmtiles)\n- `BZIP2_CMD`: Command-line tool for decompression (bzip2)\n- `FIND_CMD`: Command-line tool for file operations (find)\n- `WHOSONFIRST_DB_URL`: URL for the WhosOnFirst database\n- `PROTOMAPS_BUILDS_URL`: URL for Protomaps builds JSON list\n- `TARGET_COUNTRIES`: List of country codes to process (empty array = ALL)\n\n## License\n\nThis project is licensed under the GNU GPLv3 License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnipsysdev%2Foakality","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnipsysdev%2Foakality","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnipsysdev%2Foakality/lists"}