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:

API Trace View

Struggling with slow API calls? 🕒

Dan Mindru walks through how he used Sentry's new Trace View feature to shave off 22.3 seconds from an API call.

Get a practical walkthrough of how to identify bottlenecks, split tasks into multiple parallel tasks, identify slow AI model calls, and more.

Read more →

Top comments (0)

Billboard image

Try REST API Generation for Snowflake

DevOps for Private APIs. Automate the building, securing, and documenting of internal/private REST APIs with built-in enterprise security on bare-metal, VMs, or containers.

  • Auto-generated live APIs mapped from Snowflake database schema
  • Interactive Swagger API documentation
  • Scripting engine to customize your API
  • Built-in role-based access control

Learn more

👋 Kindness is contagious

Explore a sea of insights with this enlightening post, highly esteemed within the nurturing DEV Community. Coders of all stripes are invited to participate and contribute to our shared knowledge.

Expressing gratitude with a simple "thank you" can make a big impact. Leave your thanks in the comments!

On DEV, exchanging ideas smooths our way and strengthens our community bonds. Found this useful? A quick note of thanks to the author can mean a lot.

Okay