DEV Community

Cover image for Python: A simple web API to search for Australian postcodes based on locality aka suburb.
Be Hai Nguyen
Be Hai Nguyen

Posted on • Edited on

2 1

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

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"
                }
            ]
        }
    }
Enter fullscreen mode Exit fullscreen mode

Nothing found:

    {
        "status": {
            "code": 404,
            "text": "No localities matched 'xyz'"
        }
    }
Enter fullscreen mode Exit fullscreen mode

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'"
        }
    }
Enter fullscreen mode Exit fullscreen mode

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:

Heroku

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

Top comments (0)

Sentry image

Hands-on debugging session: instrument, monitor, and fix

Join Lazar for a hands-on session where you’ll build it, break it, debug it, and fix it. You’ll set up Sentry, track errors, use Session Replay and Tracing, and leverage some good ol’ AI to find and fix issues fast.

RSVP here →