Python SDK

ai4m-sdk is a small Python client that handles authentication, turns responses into typed objects, and raises a clear exception for each kind of error.

Install

The SDK needs Python 3.9 or newer. Install it from this site:

pip install https://docs.ai4mproject.com/downloads/ai4m_sdk-0.4.0-py3-none-any.whl

Or download the package and install the file:

pip install ai4m_sdk-0.4.0-py3-none-any.whl

The current version is 0.4.0. New versions are announced in the changelog.

Create a client

import os
from ai4m_sdk import AI4MClient

client = AI4MClient(api_key=os.environ["AI4M_API_KEY"])

Argument	Default	Meaning
`api_key`	required	Your API key
`base_url`	`https://api.ai4mproject.com`	The API’s address
`timeout`	`10.0`	Seconds to wait for a response

Methods

Method	Returns	Endpoint
`get_periods()`	`Periods`	Periods
`get_state_risk(period=None)`	`StateRiskReport`	State risk
`get_lga_risk(state, period=None)`	`LgaRiskReport`	LGA risk
`get_state_forecasts(months=None)`	list of `StateRiskReport`	State forecasts
`get_lga_forecasts(state, months=None)`	list of `LgaRiskReport`	LGA forecasts
`get_transmission()`	`TransmissionReport`	State transmission
`get_lga_seasons(state)`	`LgaSeasonReport`	LGA transmission
`get_transmission_model()`	The response as a `dict`	Transmission model
`get_state_context()`	list of `AreaContext`	State context
`get_lga_context(state)`	list of `AreaContext`	LGA context
`get_state_boundaries()`	GeoJSON as a `dict`	State boundaries
`get_lga_boundaries(state)`	GeoJSON as a `dict`	LGA boundaries

Example

periods = client.get_periods()
print(f"Estimated to {periods.last_estimated}, forecast to {periods.last_forecast}")

# The five highest-risk states this month.
report = client.get_state_risk()
for state in sorted(report.states, key=lambda s: s.score, reverse=True)[:5]:
    print(f"{state.state:<12} {state.score:.2f} ({state.score_low:.2f} to {state.score_high:.2f}) {state.level}")

# Every LGA in Kano, then its forecast.
kano = client.get_lga_risk("KN")
for report in client.get_lga_forecasts("KN", months=3):
    mean = sum(lga.score for lga in report.lgas) / len(report.lgas)
    print(report.period, round(mean, 2))

What comes back

A StateRiskReport has period, kind and a list of states. Each state has state_code, state, zone, score, score_low, score_high, level, lgas and population.

An LgaRiskReport has period, kind, state_code, state and a list of lgas. Each LGA has lga_code, lga, score, score_low, score_high, level, is_urban and population.

The field names are the same as in the API’s JSON. See Scores and levels for what they mean.

Errors

Every exception is a subclass of AI4MError, with status_code and, where the API sends one, code.

Exception	Status	Meaning
`AI4MValidationError`	400	The request was wrong
`AI4MAuthenticationError`	401	The key is missing, wrong, expired or revoked
`AI4MPermissionError`	403	The key lacks the scope
`AI4MNotFoundError`	404	Unknown state, or no data for that month
`AI4MRateLimitError`	429	A limit was reached. Has `retry_after`, in seconds

import time
from ai4m_sdk import AI4MPermissionError, AI4MRateLimitError

try:
    report = client.get_lga_risk("KN")
except AI4MRateLimitError as exc:
    if exc.code == "RATE_LIMITED":
        time.sleep(exc.retry_after or 5)   # then try again
    else:
        raise                              # QUOTA_EXCEEDED: wait for next month
except AI4MPermissionError as exc:
    print("This key can't read risk scores:", exc)