You can find more about the FSA Food Alerts API here.

However, accessing data from the API and parsing the results can be tricky- requiring multiple calls for nested data, nested for loops to access properties and the like.

The first phase of my internship project aims to solve this. I created a Python wrapper for the FSA Food Alerts API, with the ultimate aim of making the API easier to discover and use.

The wrapper makes accessing and processing data from the API very simple by abstracting away the details of HTTP requests and response parsing. This leaves the user with the freedom to analyse and process this data, with the aid of getter functions (which works well with code completion aids, such as IntelliSense), and convenience functions.

To help users get started, I have created usage examples that demonstrate how easily the wrapper can be used to access and process data from the API. These demos will be the main focus of this blog post.

Documentation is also available here which provides more information about the classes and functions in the package.

Usage Examples

Plotting the 10 most common allergens in the past year

def plotTopAllergens(f):
    yearAgo = (datetime.now() - timedelta(days=365)).isoformat()
    alerts = f.getAlerts(yearAgo)

    allergenCounts = defaultdict(int)

    alert: Alert  # type hinting for code completion
    for alert in alerts:
        allergens = alert.allergenLabels()
        for allergen in allergens:
            allergenCounts[allergen] += 1

    # get the 10 most frequently occurring allergens
    sortedAllergens = [
        (k, v)
        for k, v in sorted(
            allergenCounts.items(), key=lambda item: item[1], reverse=True
        )][:10]


    labels = [k for (k, v) in sortedAllergens]
    heights = [v for k, v in sortedAllergens]

    plt.bar(labels, heights, color="green")
    plt.xticks(rotation="vertical")
    plt.title("10 Most Common Allergens in the Past Year")
    plt.tight_layout()
    plt.show()

As you can see above, the abstraction provided by the wrapper allows for concise and readable code. The entirety of data acquisition and parsing has been done using only the wrapper methods getAlerts() and allergenLabels().

Accessing data from the API using the wrapper is as simple as calling the getAlerts() method. The Alert objects’ attributes are then easily accessible using their getter methods. We opted to use getter methods instead of accessing the attributes directly to exploit code completion aids. There is a catch, however: since Python is dynamically typed, type hinting has to be used to tell Python that a variable is an Alert object. An example is shown below.

allergenLabels() makes accessing the allergens in an alert more convenient. Accessing this attribute otherwise would be tedious due to the complex data structure of Alert objects.

Plotting the alert counts per month in 2019

def plotAlertCountPerMonth(f):
    # get alerts from 1 January 2019
    lastYear = date(2019, 1, 1).isoformat()
    alerts = f.getAlerts(lastYear)
    monthlyCount = defaultdict(int)

    # filter alerts to those created in 2019
    # and tally results
    
    alert: Alert    # type hinting for code completion
    for alert in alerts:
        yearCreated = date.fromisoformat(alert.created()).year
        monthCreated = date.fromisoformat(alert.created()).month

        if (yearCreated == 2019):
            monthlyCount[monthCreated] += 1

    xAxis = ["January", "February", "March", 
            "April", "May", "June", "July", 
            "August", "September", "October", 
            "November", "December"]

    yAxis = [monthlyCount[i] for i in range(1, 13)]

    # configuring and displaying plot
    plt.plot(xAxis, yAxis)
    plt.title("Alert count per month in 2019")
    plt.xticks(rotation=45)
    plt.tight_layout()
    plt.show()

Above is another example of data visualisation using the wrapper. The same approach applies: using getAlerts() to access data, and then obtaining useful information from the data using getter methods, in this case created().

So far, we have only used getAlerts() to obtain alerts since a given date, by providing a date string in ISO format. We can also provide an integer, n, as a parameter instead to get n alerts from the API. For example, getAlerts(5) would return 5 alerts. Note, however, that the API is non-deterministic and subsequent calls to it can return different results (even without any updates to the API database). To get deterministic results, some criteria for sorting has to be specified. To get the n most recent alerts for example, a sortBy parameter has to be provided: getAlerts(5, sortBy='-created'). This returns 5 alerts from the API, sorted by the created attribute in descending (latest first, hence the minus sign) order.getAlerts() can take more optional parameters such as filters and offsets for pagination, details of which are available in the documentation.

The wrapper also provides more methods for obtaining data from the API, namely searchAlerts() and getAlert(). searchAlerts() takes as a required parameter a string to search the API database for. It then returns a list of alerts that match the query string. getAlert(), as the name suggests, returns only one alert. It takes as parameter an alert’s notation attribute which uniquely identifies any given alert. getAlert() returns more details about a specific alert than getAlerts() does.

Creating a front-end application with the API

Next we show a short example of using the food alerts API to create a simple HTML user interface. Python’s Flask library is ideal for creating web applications which dynamically create web pages using data fetched from an API or database. In this illustration, we’ll show a set of cards with summaries of recent alerts, which the user can click through to see more details of an individual alert.

from foodAlertsAPI import foodAlertsAPI

f = foodAlertsAPI()
@app.route('/', methods=["GET", "POST"])
def alerts():
    query = request.form.get("query", "")

    if query == "":
        alerts = f.getAlerts(24)

    else:
        alerts = f.searchAlerts(query, limit=24)

    return render_template('index.html', alerts=alerts, query=query)

@app.route('/alert/')
def alertDetails(id):
    alert = f.getAlert(id)
    allergens = alert.allergenLabels()
    pathogenRisks = alert.pathogenRiskLabels()

    return render_template('alert.html', alert=alert, allergens=allergens, pathogenRisks=pathogenRisks)

The code above shows the server-side of a web application written in Flask (the front-end code is omitted for brevity).

This example serves to show how searchAlerts() and getAlert() can be used.

For the next part of my internship, I moved onto creating an automated API wrapper generator.

(a #TechTalk article)