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

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:

Oldest comments (0)