Contributing to LocationDB

LocationDB is a git-backed, community-driven project. Every location record lives in a human-readable YAML file — contributions are made via pull requests, so the entire history of additions and corrections is preserved in git.

Database Structure

The database uses a district file model. Each YAML file represents a geographic district and contains all suburbs within it as named keys:

database/
└── continent/
    └── region/
        └── country/
            └── admin1/
                └── DistrictName.yaml

A district YAML file looks like this:

Bondi Beach:
  id: 861af882-4a1e-4687-bae4-0ecb5caa9f55
  latitude: -33.8915
  longitude: 151.2767
  postcode: "2026"

Coogee:
  id: 3f4e1a2b-5c6d-7e8f-9a0b-1c2d3e4f5a6b
  latitude: -33.9216
  longitude: 151.2573
  postcode: "2034"

Each suburb entry contains exactly four fields:

Field	Type	Required	Description
id	UUID string	Yes	Unique identifier — never change this once set
latitude	Number	Yes	Decimal degrees, −90 to 90
longitude	Number	Yes	Decimal degrees, −180 to 180
postcode	String	Recommended	Quote to preserve leading zeros (e.g. "0200")

Why district files?

This model has two advantages over one-file-per-suburb:

1. Git-friendly diffs — A PR adding five suburbs to the same district touches exactly one file. Reviewers see exactly what changed.
2. Scalability — The repository stays shallow (hundreds of files rather than tens of thousands), making clones and directory traversal fast.

Geographic hierarchy levels

Level	Description	Examples
continent	Seven continents	Africa, Asia, Europe, Oceania
region	Sub-continental grouping	Eastern Africa, South-East Asia, Western Europe
country	ISO 3166 country name	Australia, South Africa, Germany
admin1	First administrative division	State, province, region
district file	Named district file (e.g. Sydney.yaml)	City, LGA, SA3, county
suburb key	Key within the district file	Suburb, town, locality, neighbourhood

Not all levels are required. A country with only a handful of locations might have just continent/region/country.yaml with the locations keyed directly.

How to Add Locations

Option A — Flask admin app (recommended for local work)

Run the admin app locally and use the web interface to browse to the right district, then click Add Suburb.

cd flask
pip install -r requirements.txt
python app.py

Open http://localhost:5000 in your browser.

Option B — Edit YAML files directly

1. Find or create the appropriate district YAML file.

2. Add a new keyed entry. Generate a UUID at uuidgenerator.net or with Python:

   python import uuid; print(uuid.uuid4())

3. Keep entries sorted alphabetically by suburb name (the write tool enforces this automatically; manual edits should follow suit).

Example — adding a new suburb to an existing file:

# database/Oceania/Australia and New Zealand/Australia/New South Wales/Eastern Suburbs.yaml

Bondi Beach:
  id: 861af882-4a1e-4687-bae4-0ecb5caa9f55
  latitude: -33.8915
  longitude: 151.2767
  postcode: "2026"

# New entry:
Bronte:
  id: <your-new-uuid>
  latitude: -33.9041
  longitude: 151.2652
  postcode: "2024"

Coogee:
  id: 3f4e1a2b-5c6d-7e8f-9a0b-1c2d3e4f5a6b
  latitude: -33.9216
  longitude: 151.2573
  postcode: "2034"

Creating a new district file

If no suitable district file exists, create one:

database/Oceania/Australia and New Zealand/Australia/Victoria/Inner Melbourne.yaml

The file path encodes the geographic hierarchy. The file stem (Inner Melbourne) becomes the district label.

Submission Process

1. Fork the LocationDB repository.
2. Create a branch: bash git checkout -b add-inner-melbourne
3. Add or edit the relevant district YAML file(s).
4. Validate your changes: bash cd tools python from_database.py This checks for duplicate or missing UUIDs across the entire database and exits with an error if any are found.
5. Commit only the district file(s) you changed — one district per commit keeps diffs readable.
6. Open a pull request with a brief description of what you added and the source of your coordinate data.

Data Quality Guidelines

Do

• Use accurate coordinates from reliable sources (OpenStreetMap, government GIS portals, GPS).
• Include postcodes where available.
• Follow the established directory structure.
• Generate a fresh UUID for each new entry.
• Test with from_database.py before submitting.

Don't

• Duplicate an existing entry (the validator will catch this).
• Change an existing UUID — applications may depend on its stability.
• Use approximate or guessed coordinates.
• Submit entries without a postcode if one is publicly available.

Validating Your Changes

cd tools
python from_database.py

A successful run prints:

id validation passed for N records

Any errors (missing IDs, duplicates, malformed entries) are printed with file references before the script exits non-zero.

Getting Help

• Questions: Open a GitHub Discussion
• Issues: Report problems via GitHub Issues
• Examples: Browse database/ for reference files

Thank you for contributing to LocationDB!