{"id":20030924,"url":"https://github.com/mountain-pass/addressr","last_synced_at":"2026-05-24T22:04:54.263Z","repository":{"id":38314531,"uuid":"196473469","full_name":"mountain-pass/addressr","owner":"mountain-pass","description":"Free Australian Address Validation, Search and Autocomplete","archived":false,"fork":false,"pushed_at":"2026-05-24T15:09:40.000Z","size":9501,"stargazers_count":109,"open_issues_count":27,"forks_count":23,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-05-24T15:26:05.875Z","etag":null,"topics":["address","australia","autocomplete","autosuggest","g-naf","geo","geocoding","street-address","swagger","validation"],"latest_commit_sha":null,"homepage":"https://addressr.io","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mountain-pass.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":"governance/control-traceability.json","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2019-07-11T22:39:59.000Z","updated_at":"2026-05-24T15:09:44.000Z","dependencies_parsed_at":"2024-06-21T13:01:54.828Z","dependency_job_id":"08cda34b-d595-4e66-bb28-234404914af4","html_url":"https://github.com/mountain-pass/addressr","commit_stats":{"total_commits":833,"total_committers":8,"mean_commits":104.125,"dds":0.4741896758703481,"last_synced_commit":"054c1b13f68d4ccbe3cb01ee2108380573e8ba4b"},"previous_names":[],"tags_count":207,"template":false,"template_full_name":null,"purl":"pkg:github/mountain-pass/addressr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mountain-pass%2Faddressr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mountain-pass%2Faddressr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mountain-pass%2Faddressr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mountain-pass%2Faddressr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mountain-pass","download_url":"https://codeload.github.com/mountain-pass/addressr/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mountain-pass%2Faddressr/sbom","scorecard":{"id":661515,"data":{"date":"2025-08-11","repo":{"name":"github.com/mountain-pass/addressr","commit":"f0eb2faa6098e69e5a912e4b6af70c73e5b380a3"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.2,"checks":[{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Code-Review","score":0,"reason":"Found 0/18 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":7,"reason":"8 commit(s) and 1 issue activity found in the last 90 days -- score normalized to 7","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/release.yml:1","Warn: no topLevel permission defined: .github/workflows/reusable-update.yml:1","Warn: no topLevel permission defined: .github/workflows/update-act.yml:1","Warn: no topLevel permission defined: .github/workflows/update-nsw.yml:1","Warn: no topLevel permission defined: .github/workflows/update-nt.yml:1","Warn: no topLevel permission defined: .github/workflows/update-ot.yml:1","Warn: no topLevel permission defined: .github/workflows/update-qld.yml:1","Warn: no topLevel permission defined: .github/workflows/update-sa.yml:1","Warn: no topLevel permission defined: .github/workflows/update-tas.yml:1","Warn: no topLevel permission defined: .github/workflows/update-vic.yml:1","Warn: no topLevel permission defined: .github/workflows/update-wa.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Pinned-Dependencies","score":1,"reason":"dependency not pinned by hash detected -- score normalized to 1","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/mountain-pass/addressr/release.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/release.yml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/mountain-pass/addressr/release.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:32: update your workflow using https://app.stepsecurity.io/secureworkflow/mountain-pass/addressr/release.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:35: update your workflow using https://app.stepsecurity.io/secureworkflow/mountain-pass/addressr/release.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/release.yml:41: update your workflow using https://app.stepsecurity.io/secureworkflow/mountain-pass/addressr/release.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/release.yml:55: update your workflow using https://app.stepsecurity.io/secureworkflow/mountain-pass/addressr/release.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/reusable-update.yml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/mountain-pass/addressr/reusable-update.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/reusable-update.yml:24: update your workflow using https://app.stepsecurity.io/secureworkflow/mountain-pass/addressr/reusable-update.yml/master?enable=pin","Warn: containerImage not pinned by hash: Dockerfile:2","Warn: npmCommand not pinned by hash: Dockerfile:26","Warn: npmCommand not pinned by hash: scripts/run.sh:5","Info:   0 out of   5 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   3 third-party GitHubAction dependencies pinned","Info:   1 out of   3 npmCommand dependencies pinned","Info:   0 out of   1 containerImage dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: Apache License 2.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 15 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":0,"reason":"58 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-968p-4wvh-cqc8","Warn: Project is vulnerable to: GHSA-93q8-gq69-wqmw","Warn: Project is vulnerable to: GHSA-fwr7-v2mv-hh25","Warn: Project is vulnerable to: GHSA-67hx-6x53-jw92","Warn: Project is vulnerable to: GHSA-pp7h-53gx-mx7r","Warn: Project is vulnerable to: GHSA-qwcr-r2fm-qrc7","Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw","Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg","Warn: Project is vulnerable to: GHSA-h452-7996-h45h","Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275","Warn: Project is vulnerable to: GHSA-9vvw-cc9w-f27h","Warn: Project is vulnerable to: GHSA-gxpj-cx7g-858c","Warn: Project is vulnerable to: GHSA-w573-4hg7-7wgq","Warn: Project is vulnerable to: GHSA-wm7h-9275-46v2","Warn: Project is vulnerable to: GHSA-4gmj-3p3h-gm8h","Warn: Project is vulnerable to: GHSA-fjxv-7rqg-78g4","Warn: Project is vulnerable to: GHSA-4q6p-r6v2-jvc5","Warn: Project is vulnerable to: GHSA-pfrx-2q88-qq97","Warn: Project is vulnerable to: GHSA-rc47-6667-2j5j","Warn: Project is vulnerable to: GHSA-qqgx-2p2h-9c37","Warn: Project is vulnerable to: GHSA-7r28-3m3f-r2pr","Warn: Project is vulnerable to: GHSA-r8j5-h5cx-65gg","Warn: Project is vulnerable to: GHSA-8gwj-8hxc-285w","Warn: Project is vulnerable to: GHSA-9c47-m6qq-7p4h","Warn: Project is vulnerable to: GHSA-282f-qqgm-c34q","Warn: Project is vulnerable to: GHSA-jf85-cpcp-j695","Warn: Project is vulnerable to: GHSA-fvqr-27wr-82fm","Warn: Project is vulnerable to: GHSA-4xc9-xhrj-v574","Warn: Project is vulnerable to: GHSA-x5rq-j2xg-h7qm","Warn: Project is vulnerable to: GHSA-29mw-wpgm-hmr9","Warn: Project is vulnerable to: GHSA-35jh-r3h4-6jhm","Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv","Warn: Project is vulnerable to: GHSA-hxm2-r34f-qmc5","Warn: Project is vulnerable to: GHSA-f8q6-p94x-37v3","Warn: Project is vulnerable to: GHSA-vh95-rmgr-6w4m","Warn: Project is vulnerable to: GHSA-xvch-5gv4-984h","Warn: Project is vulnerable to: GHSA-w9mr-4mfr-499f","Warn: Project is vulnerable to: GHSA-44fp-w29j-9vj5","Warn: Project is vulnerable to: GHSA-r683-j2x4-v87g","Warn: Project is vulnerable to: GHSA-px4h-xg32-q955","Warn: Project is vulnerable to: GHSA-rp65-9cf3-cjxr","Warn: Project is vulnerable to: GHSA-hj48-42vr-x3v9","Warn: Project is vulnerable to: GHSA-rhx6-c78j-4q9w","Warn: Project is vulnerable to: GHSA-9wv6-86v2-598j","Warn: Project is vulnerable to: GHSA-gqgv-6jq5-jjj9","Warn: Project is vulnerable to: GHSA-hrpp-h998-j3pp","Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw","Warn: Project is vulnerable to: GHSA-44c6-4v22-4mhx","Warn: Project is vulnerable to: GHSA-4x5v-gmq8-25ch","Warn: Project is vulnerable to: GHSA-g4rg-993r-mgx7","Warn: Project is vulnerable to: GHSA-29xr-v42j-r956","Warn: Project is vulnerable to: GHSA-52f5-9888-hmc6","Warn: Project is vulnerable to: GHSA-7p7h-4mm5-852v","Warn: Project is vulnerable to: GHSA-6jrj-vc65-c983","Warn: Project is vulnerable to: GHSA-chw2-6c7r-37p7","Warn: Project is vulnerable to: GHSA-qgmg-gppg-76g5","Warn: Project is vulnerable to: GHSA-g3ch-rx76-35fx","Warn: Project is vulnerable to: GHSA-j8xg-fqg3-53r7"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-21T16:20:54.519Z","repository_id":38314531,"created_at":"2025-08-21T16:20:54.519Z","updated_at":"2025-08-21T16:20:54.519Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33452050,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-24T19:21:36.376Z","status":"ssl_error","status_checked_at":"2026-05-24T19:21:10.562Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["address","australia","autocomplete","autosuggest","g-naf","geo","geocoding","street-address","swagger","validation"],"created_at":"2024-11-13T09:29:26.338Z","updated_at":"2026-05-24T22:04:54.256Z","avatar_url":"https://github.com/mountain-pass.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Addressr\n\n![Addressr](https://addressr.io/icons/icon-144x144.png 'Addressr')\n\n**The only open-source, free self-hosted Australian address validation API.**\n\n[Australian Address Validation, Search and Autocomplete](https://addressr.io) — [addressr.io](https://addressr.io)\n\n[![GitHub license](https://img.shields.io/github/license/mountain-pass/addressr)](https://github.com/mountain-pass/addressr/blob/master/LICENSE) [![npm](https://img.shields.io/npm/v/@mountainpass/addressr)](https://www.npmjs.com/package/@mountainpass/addressr) [![npm downloads](https://img.shields.io/npm/dm/@mountainpass/addressr)](https://www.npmjs.com/package/@mountainpass/addressr)\n\n[![GitHub issues](https://img.shields.io/github/issues/mountain-pass/addressr)](https://github.com/mountain-pass/addressr/issues) [![GitHub pull requests](https://img.shields.io/github/issues-pr/mountain-pass/addressr)](https://github.com/mountain-pass/addressr/pulls)\n\n# About\n\nAustralian Address Validation, Search and Autocomplete powered by the Geocoded National Address File (G-NAF), Australia's **authoritative** address database with 15+ million addresses.\n\n- **Validated addresses** from the official G-NAF source\n- **Real-time autocomplete** with fuzzy matching\n- **Locality, postcode, and state search** for area pickers\n- **Geocoding** to latitude/longitude (optional)\n- **Self-hosted or SaaS** — your choice, your data\n- **Open source** — audit the code, customize as needed\n\n# Why Addressr\n\n|                                    | Addressr | [Addressify](https://addressify.com.au/) | [AddressFinder](https://addressfinder.com.au/) | [Geoscape](https://geoscape.com.au/) | Google Maps |\n| ---------------------------------- | -------- | ---------------------------------------- | ---------------------------------------------- | ------------------------------------ | ----------- |\n| Self-hosted                        | ✅       | ❌                                       | ❌                                             | ❌                                   | ❌          |\n| Open source                        | ✅       | ❌                                       | ❌                                             | ❌                                   | ❌          |\n| Free tier (unlimited, self-hosted) | ✅       | ❌                                       | ❌                                             | ❌                                   | ❌          |\n| G-NAF data source                  | ✅       | ✅                                       | ✅                                             | ✅ (creator)                         | ❌          |\n| Data sovereignty                   | ✅       | ❌                                       | ❌                                             | ❌                                   | ❌          |\n| MCP integration for AI assistants  | ✅       | ❌                                       | ❌                                             | ❌                                   | ❌          |\n\n**Stop paying Google Maps for Australian addresses.** Stop locking your data into third-party SaaS. Addressr gives you unlimited address validation on your own infrastructure, or a cheap hosted API if you prefer.\n\n# Quick Start\n\n## Use the Hosted API\n\nThe fastest way to get started. No infrastructure to manage.\n\n1. Get an API key at [RapidAPI](https://rapidapi.com/addressr-addressr-default/api/addressr)\n2. Search for an address:\n\n   ```sh\n   curl \"https://addressr.p.rapidapi.com/addresses?q=1+george+st+sydney\" \\\n     -H \"x-rapidapi-key: YOUR_KEY\" \\\n     -H \"x-rapidapi-host: addressr.p.rapidapi.com\"\n   ```\n\n## Use with AI Assistants\n\nConnect Addressr to Claude, Cursor, VS Code Copilot, or any MCP-compatible AI assistant.\n\n```json\n{\n  \"mcpServers\": {\n    \"addressr\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@mountainpass/addressr-mcp\"],\n      \"env\": { \"RAPIDAPI_KEY\": \"your-key\" }\n    }\n  }\n}\n```\n\nThree tools available: **search-addresses**, **get-address**, and **health**. See [@mountainpass/addressr-mcp](https://github.com/mountain-pass/addressr-mcp) for full setup instructions.\n\n## Self Hosted\n\nRun Addressr on your own infrastructure for full control over your data.\n\n1. Install addressr\n\n   ```\n   npm install @mountainpass/addressr -g\n   ```\n\n   NOTE: If you are running windows, you'll need to use [wsl](https://docs.microsoft.com/en-us/windows/wsl/install-win10)\n\n2. Start open search. For example run\n\n   ```\n   docker pull opensearchproject/opensearch:1.3.20\n   docker run -p 9200:9200 -p 9300:9300 -e \"discovery.type=single-node\" -e \"plugins.security.disabled=true\" opensearchproject/opensearch:1.3.20\n   ```\n\n3. Start API server. In a second window run:\n\n   ```sh\n   export ELASTIC_PORT=9200\n   export ELASTIC_HOST=localhost\n   addressr-server-2\n   ```\n\n4. Setup the env vars for the data loader. In a third window run:\n\n   ```\n   export ELASTIC_PORT=9200\n   export ELASTIC_HOST=localhost\n   export ADDRESSR_INDEX_TIMEOUT=30s\n   export ADDRESSR_INDEX_BACKOFF=1000\n   export ADDRESSR_INDEX_BACKOFF_INCREMENT=1000\n   export ADDRESSR_INDEX_BACKOFF_MAX=10000\n   ```\n\n   1. Optional — enable geocodes by setting the following env vars for the data loader. In the third window run:\n      **NOTE:** with geocodes enabled, indexing takes much longer and needs much more memory. Only turn them on if you need them. You can always add them later.\n\n   ```\n   export ADDRESSR_ENABLE_GEO=1\n   export NODE_OPTIONS=--max_old_space_size=8196\n   ```\n\n   2. Optional — limit the addresses to a single state by setting the `COVERED_STATES` env var for the data loader.\n      This dramatically speeds up indexing. For example, in the third window run:\n\n   ```\n   export COVERED_STATES=VIC,SA\n   ```\n\n   Valid values are:\n   - ACT\n   - NSW\n   - NT\n   - OT\n   - QLD\n   - SA\n   - TAS\n   - VIC\n   - WA\n\n5. Run data Loader. In the third window run:\n\n   ```\n   addressr-loader\n   ```\n\n6. OK, so we stretched the truth a bit with the \"Quick Start\" heading. The truth is that it takes quite a while to download, store and index the 15+ million addresses from [data.gov.au](http://data.gov.au/). So make a coffee, or tea, or find something else to do and come back in about an hour when it's done.\n\n7. Search for an address using the command line\n\n   ```\n   curl -i http://localhost:8080/addresses?q=LEVEL+25,+TOWER+3\n   ```\n\n8. An updated G-NAF is released every 3 months. Put `addressr-loader` in a cron job or similar to keep addressr regularly updated\n9. Wire your address form up to the address-server api.\n\n# API Endpoints\n\nAddressr exposes a HATEOAS REST API. Start at the root (`/`) and follow links to discover endpoints. A supplementary OpenAPI 3.x spec is available at `/api-docs`.\n\n| Endpoint                     | Purpose                                                            | Example                           |\n| ---------------------------- | ------------------------------------------------------------------ | --------------------------------- |\n| `GET /addresses?q=`          | Search and autocomplete addresses                                  | `/addresses?q=1+george+st+sydney` |\n| `GET /addresses/{pid}`       | Get full address details (with links to locality, postcode, state) | `/addresses/GAOT_717882967`       |\n| `GET /localities?q=`         | Search suburbs/localities by name                                  | `/localities?q=lilydale`          |\n| `GET /localities/{pid}`      | Get locality details (with links to postcode, state)               | `/localities/loc9984d8beb142`     |\n| `GET /postcodes?q=`          | Search postcodes (q optional)                                      | `/postcodes?q=3140`               |\n| `GET /postcodes/{postcode}`  | Get postcode with associated localities                            | `/postcodes/6798`                 |\n| `GET /states?q=`             | Search states/territories (q optional)                             | `/states?q=New`                   |\n| `GET /states/{abbreviation}` | Get state details                                                  | `/states/NSW`                     |\n| `GET /api-docs`              | OpenAPI 3.x specification                                          | `/api-docs`                       |\n| `GET /health`                | Health check                                                       | `/health`                         |\n\n## How it Works\n\n![How it works](https://addressr.io/static/addressr-fe45ac1ba82b1dd5224f1c7356dfd1ca.svg 'How it works')\n\n## Additional Settings\n\n| Environment Variable                   | Value       | Description                                                                                               | Default |\n| -------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------- | ------- |\n| ELASTIC_PROTOCOL                       | http        | Connect to open search over http                                                                          | ✅      |\n| ELASTIC_PROTOCOL                       | https       | Connect to open search over https                                                                         |         |\n| ELASTIC_USERNAME                       | _blank_     | Connect to open search without authentication                                                             | ✅      |\n| ELASTIC_USERNAME                       | _non-blank_ | Connect to open search with the specified username                                                        |         |\n| ELASTIC_PASSWORD                       | _blank_     | Connect to open search without authentication                                                             | ✅      |\n| ELASTIC_PASSWORD                       | _non-blank_ | Connect to open search with the specified password                                                        |         |\n| PAGE_SIZE                              | 8           | Number or records to return in a search                                                                   | ✅      |\n| ADDRESSR_ACCESS_CONTROL_ALLOW_ORIGIN   | _blank_     | An `Access-Control-Allow-Origin` response header is **not** returned                                      | ✅      |\n| ADDRESSR_ACCESS_CONTROL_ALLOW_ORIGIN   | _non-blank_ | An `Access-Control-Allow-Origin` response header is returned with the value in the environment variable   |         |\n| ADDRESSR_ACCESS_CONTROL_EXPOSE_HEADERS | _blank_     | An `Access-Control-Expose-Headers` response header is **not** returned                                    | ✅      |\n| ADDRESSR_ACCESS_CONTROL_EXPOSE_HEADERS | _non-blank_ | An `Access-Control-Expose-Headers` response header is returned with the value in the environment variable |         |\n| ADDRESSR_ACCESS_CONTROL_ALLOW_HEADERS  | _blank_     | An `Access-Control-Allow-Headers` response header is **not** returned                                     | ✅      |\n| ADDRESSR_ACCESS_CONTROL_ALLOW_HEADERS  | _non-blank_ | An `Access-Control-Allow-Headers` response header is returned with the value in the environment variable  |         |\n| ADDRESSR_PROXY_AUTH_HEADER             | _blank_     | No gateway auth header enforcement (self-hosted default)                                                  | ✅      |\n| ADDRESSR_PROXY_AUTH_HEADER             | _non-blank_ | Name of the header the origin requires — set alongside `ADDRESSR_PROXY_AUTH_VALUE`                        |         |\n| ADDRESSR_PROXY_AUTH_VALUE              | _blank_     | No gateway auth header enforcement (self-hosted default)                                                  | ✅      |\n| ADDRESSR_PROXY_AUTH_VALUE              | _non-blank_ | Expected value the header must carry — set alongside `ADDRESSR_PROXY_AUTH_HEADER`                         |         |\n\n### Gateway auth header (optional)\n\nBy default Addressr does not enforce any proxy authentication — self-hosted npm and Docker deployments work with zero configuration.\n\nIf you front Addressr with an API gateway (RapidAPI, Kong, Tyk, Apigee, AWS API Gateway, nginx, Caddy, or your own Cloudflare Worker) and want the origin to reject traffic that bypasses your gateway, set both environment variables to the header name your gateway injects and the shared secret it forwards:\n\n| Variable                     | Example                   | Notes                                       |\n| ---------------------------- | ------------------------- | ------------------------------------------- |\n| `ADDRESSR_PROXY_AUTH_HEADER` | `X-RapidAPI-Proxy-Secret` | Header name your gateway forwards           |\n| `ADDRESSR_PROXY_AUTH_VALUE`  | `\u003cyour-gateway-secret\u003e`   | Expected value; keep out of version control |\n\nBehaviour:\n\n- Both unset → no enforcement (default).\n- Both set → requests without a matching header receive `401 Authentication required`.\n- Exactly one set → the process exits at startup with a clear error (fails loud to prevent silent bypass).\n- `/health` and `/api-docs` remain reachable without the header so uptime monitors and gateway OpenAPI imports keep working.\n\nSee [ADR 024](docs/decisions/024-origin-gateway-auth-header-enforcement.proposed.md) for the decision record.\n\nNOTE: When adjusting PAGE_SIZE, you should take into account how quickly you want the initial results returned to the user. In many use cases, you want this to be as fast as possible. If you need show more results to the user, you are often better off leaving it a 8 and using the paging links to get more results while you are displaying the first 8.\n\nWhy is the default 8 and not 10? [Mechanical Sympathy](https://dzone.com/articles/mechanical-sympathy)\n\n## System requirements\n\n### Open Search\n\nopensearch \u003e= 1.2.4 with 1.4GiB of memory\n\n### Addressr Loader\n\n#### Default\n\nNode.js \u003e= 22 with 1GiB of memory\n\n#### With Geocoding enabled\n\nNode.js \u003e= 22 with 8GiB of memory\n\n### Addressr Server\n\nNode.js \u003e= 22 with 64MiB of memory\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmountain-pass%2Faddressr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmountain-pass%2Faddressr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmountain-pass%2Faddressr/lists"}