# Food Alerts API Python Wrapper

The FSA Food Alerts API provides data on alerts regarding food safety and hygiene, ranging from undeclared allergens to pathogen risks. The dataset the API provides has tremendous potential for data analysis which can provide interesting insights about the food market.

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](https://food-alerts-wrapper.readthedocs.io/en/latest/) 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()

<br>

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
***




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/<id>')
def alertDetails(id):
alert = f.getAlert(id)
allergens = alert.allergenLabels()
pathogenRisks = alert.pathogenRiskLabels()

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

<br>

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

This example might be less interesting from a data analysis standpoint, but it serves to show how `searchAlerts()` and `getAlert()` can be used.
f