State forecasts

GEThttps://api.ai4mproject.com/v1/forecasts/statesScope: forecasts

Returns forecast risk scores for all 37 states, one report for each month after the latest estimated month.

Parameters

Name	Type	Required	Description
`months`	integer	No	How many months ahead to return, from 1 to 4. Defaults to 4

Parameters go in the query string.

Request

curl "https://api.ai4mproject.com/v1/forecasts/states?months=2" \
  -H "Authorization: Bearer $AI4M_API_KEY"

for report in client.get_state_forecasts(months=2):
    print(report.period, report.states[0].state, report.states[0].score)

for (const report of await client.getStateForecasts(2)) {
  console.log(report.period, report.states[0].state, report.states[0].score);
}

reports, err := client.StateForecasts(ctx, 2)
if err != nil {
  log.Fatal(err)
}
for _, report := range reports {
  fmt.Println(report.Period, report.States[0].State, report.States[0].Score)
}

Response

Field	Type	Description
`forecasts`	array	One report per month, nearest month first
`forecasts[].period`	string	The month the scores are for
`forecasts[].kind`	string	Always `forecast` for this endpoint
`forecasts[].states`	array	The same fields as State risk

{
  "forecasts": [
    {
      "period": "2026-08",
      "kind": "forecast",
      "states": [
        {
          "state_code": "ZA",
          "state": "Zamfara",
          "zone": "North West",
          "score": 0.554,
          "score_low": 0.41,
          "score_high": 0.685,
          "level": "very_high",
          "lgas": 14,
          "population": 4853077
        },
        {
          "state_code": "KE",
          "state": "Kebbi",
          "zone": "North West",
          "score": 0.527,
          "score_low": 0.38,
          "score_high": 0.657,
          "level": "very_high",
          "lgas": 21,
          "population": 4680318
        }
      ]
    },
    {
      "period": "2026-09",
      "kind": "forecast",
      "states": [
        {
          "state_code": "ZA",
          "state": "Zamfara",
          "zone": "North West",
          "score": 0.555,
          "score_low": 0.41,
          "score_high": 0.683,
          "level": "very_high",
          "lgas": 14,
          "population": 4853077
        },
        {
          "state_code": "KE",
          "state": "Kebbi",
          "zone": "North West",
          "score": 0.527,
          "score_low": 0.388,
          "score_high": 0.655,
          "level": "very_high",
          "lgas": 21,
          "population": 4680318
        }
      ]
    }
  ]
}

The example was requested with months=2 and shows two states in each month.

Errors

Code	Status	When
`INVALID_MONTHS`	400	`months` is not a whole number from 1 to 4
`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

Estimated and forecast months