Flexible Flask Endpoints for Hierarchical Local News on SuburbStory

#python #flask #google #cloud

SuburbStory publishes automated local news pages for every suburb in NSW (Australia). The site’s URLs follow a clear geographic hierarchy:

https://suburbstory.com/<country>/<state>/<area>/<suburb>/

Each page is built by aggregating structured data from multiple government sources such as police, fire, traffic, and council feeds. This data is then processed via the Gemini API to generate readable content.

A key challenge is efficiently mapping thousands of geographic URL combinations to a single Flask application.

Dynamic Routing in Flask

Rather than creating a route for each suburb, SuburbStory uses a single, flexible Flask route:

@app.route("/<country>/<state>/<area>/<suburb>/")
def suburb_page(country, state, area, suburb):
    key = f"{country}/{state}/{area}/{suburb}"
    data = fetch_suburb_doc(key)  # fetch data from Firestore
    return render_template("suburb.html", data=data)

Flask automatically parses the URL segments and passes them as function arguments. The handler then retrieves the corresponding Firestore document and renders it with a single template. This allows one route to serve thousands of unique pages across different areas and suburbs without modifying the code.

Real Examples

Two suburbs under the same area illustrate the approach:

These pages use the same route and template while aggregating their own data, demonstrating how hierarchical Flask endpoints efficiently handle multiple suburbs.

Why Hierarchical URLs Matter

The hierarchical pattern country/state/area/suburb has several advantages:

Predictable and SEO-friendly URLs – easy to link externally and for search engines to index.
Direct mapping to Firestore – each page can be stored under a document key like "au/nsw/willoughby/chatswood", simplifying retrieval.
Template reusability – the same suburb.html template dynamically adjusts based on the URL variables.
Scalable architecture – Cloud Run handles all routes in one Flask app, allowing horizontal scaling without additional routing configuration.

Takeaways for Python Developers

SuburbStory demonstrates how flexible Flask routing enables:

Serving thousands of hierarchical pages from a single route
Efficiently handling independent data fetches per page
Scaling a serverless Flask app on Cloud Run without duplicating code
Maintaining clean, predictable, SEO-friendly URLs that map directly to Firestore

This is a practical model for building large-scale local or multi-tenant content systems in Python.