State risk

GEThttps://api.ai4mproject.com/v1/risk/statesScope: risk_scores

Returns the estimated risk score for all 37 states for one month.

Parameters

Name	Type	Required	Description
`period`	string	No	The month, as `YYYY-MM`. Defaults to the latest estimated month. Must not be a forecast month

Parameters go in the query string.

Request

curl "https://api.ai4mproject.com/v1/risk/states?period=2026-07" \
  -H "Authorization: Bearer $AI4M_API_KEY"

report = client.get_state_risk(period="2026-07")
for state in report.states:
    print(state.state, state.score, state.level)

const report = await client.getStateRisk("2026-07");
for (const state of report.states) {
  console.log(state.state, state.score, state.level);
}

report, err := client.StateRisk(ctx, "2026-07")
if err != nil {
  log.Fatal(err)
}
for _, state := range report.States {
  fmt.Println(state.State, state.Score, state.Level)
}

Response

Field	Type	Description
`period`	string	The month the scores are for
`kind`	string	Always `estimated` for this endpoint
`states[].state_code`	string	Two-letter state code
`states[].state`	string	State name
`states[].zone`	string	Geopolitical zone
`states[].score`	number	Risk score from 0 to 1
`states[].score_low`	number	Lower end of the likely range
`states[].score_high`	number	Upper end of the likely range
`states[].level`	string	`very_low`, `low`, `moderate`, `high` or `very_high`
`states[].lgas`	integer	Number of LGAs in the state
`states[].population`	integer	People living in the state

{
  "period": "2026-07",
  "kind": "estimated",
  "states": [
    {
      "state_code": "ZA",
      "state": "Zamfara",
      "zone": "North West",
      "score": 0.55,
      "score_low": 0.423,
      "score_high": 0.677,
      "level": "very_high",
      "lgas": 14,
      "population": 4853077
    },
    {
      "state_code": "KE",
      "state": "Kebbi",
      "zone": "North West",
      "score": 0.528,
      "score_low": 0.401,
      "score_high": 0.655,
      "level": "very_high",
      "lgas": 21,
      "population": 4680318
    }
  ]
}

The example shows two of the 37 states. States are returned highest risk first.

Errors

Code	Status	When
`INVALID_PERIOD`	400	`period` is not in the form `YYYY-MM`
`FORECAST_PERIOD`	400	`period` is a forecast month. Use the matching forecast endpoint
`PERIOD_NOT_AVAILABLE`	404	`period` is outside the months the data covers
`SCOPE_REQUIRED`	403	The key does not include the scope this endpoint needs

Any request can also return 401 for a bad key and 429 when a limit is reached. See Errors.

See also