Python: A simple web API to search for Australian postcodes based on locality aka suburb.

#australian #postcode #api

Using the Flask-RESTX library to implement a simple web API to search for Australian postcodes based on locality aka suburb.

🚀 Full source code and documentation: https://github.com/behai-nguyen/bh_aust_postcode

The web service also implements a CLI which downloads Australian postcodes in JSON format, then extracts locality, state and postcode fields and stores them in a SQLite database file.

There are just a bit more than 18,500 (eighteen thousand five hundred) postcodes. At runtime, they are loaded once into a list property of a singleton class instance. Searches are carried out using this list, that is in memory only.

Searches are always partial: i.e. any locality contains the incoming search text is considered a match. For example, if the incoming search text is spring, then Springfield is a match.

The web API returns the search result as a JSON object.

On successful:

    {
        "status": {
            "code": 200,
            "text": ""
        },
        "data": {
            "localities": [
                {
                    "locality": "ALICE SPRINGS",
                    "state": "NT",
                    "postcode": "0870"
                },
                ...
            {
                    "locality": "WILLOW SPRINGS",
                    "state": "SA",
                    "postcode": "5434"
                }
            ]
        }
    }

Nothing found:

    {
        "status": {
            "code": 404,
            "text": "No localities matched 'xyz'"
        }
    }

Invalid searches:

    {
        "status": {
            "code": 400,
            "text": "'%^& Spring' is invalid. Accept only letters, space, hyphen and single quote characters."
        }
    }

    {
        "status": {
            "code": 400,
            "text": "Must have at least 3 characters: 'Sp'"
        }
    }

In general ['status']['code'] other than HTTPStatus.OK.value signifies search does not return any localities. Always check for ['status']['code'] of HTTPStatus.OK.value before proceeding any further with the result.

🚀 GitHub Read Me should have all necessary documentation on how to get this project to run on your development server, I have tested for both Windows 10 and Ubuntu 22.10.

My other post on Flask-RESTX -- Python: Flask-RESTX and the Swagger UI automatic documentation.

Thank you for reading. I do hope someone will find this project useful. Stay safe as always.

✿✿✿

Feature image sources:

This site is built on Heroku

Join the ranks of developers at Salesforce, Airbase, DEV, and more who deploy their mission critical applications on Heroku. Sign up today and launch your first app!

Get Started