Get Forecast Overview

Coming Soon — This endpoint is under development and will be available at a future date.

Get a 48-hour, hour-by-hour forecast that consolidates environmental, wildlife, and plant risks, plus active weather alerts, into a single summarized view. Available in two formats: a simple cacheable GET request, or an advanced POST request with full personalization options.

Simple Request (GET)

Headers

Authorization

string

required

Your API key for authentication. Format: Bearer YOUR_API_KEY

Query Parameters

location

string

required

The latitude and longitude for the location to check, formatted as {latitude},{longitude}.

options

object

Configuration options that control how the response is built.

Show options properties

options.length

string

Controls the length of the forecast summary text for each hour. Available options:

brief: 1-2 sentences focusing on the most critical risks
standard: 3-4 sentences with key risks and basic context (default)
detailed: 5-7 sentences with comprehensive risk analysis and detailed recommendations

options.exclude

string

Comma-separated list of sections to exclude from the response. Options: alerts, environment, wildlife, plants, activity_intelligence

Example

# Basic request
curl "http://api.goes.health/v1/risks/overview/forecast?location=37.7485,-119.5331" \
  -H "Authorization: Bearer YOUR_API_KEY"

# With options
curl "http://api.goes.health/v1/risks/overview/forecast?location=37.7485,-119.5331&options.length=detailed&options.exclude=alerts" \
  -H "Authorization: Bearer YOUR_API_KEY"

Advanced Request (POST)

Headers

Authorization

string

required

Your API key for authentication. Format: Bearer YOUR_API_KEY

Body Parameters

location

string

required

The latitude and longitude for the location to check, formatted as {latitude},{longitude}.

options

object

Configuration options that control how the response is built.

Show options properties

options.length

string

Controls the length of the forecast summary text for each hour. Available options:

brief: 1-2 sentences focusing on the most critical risks
standard: 3-4 sentences with key risks and basic context (default)
detailed: 5-7 sentences with comprehensive risk analysis and detailed recommendations

options.exclude

array

A list of sections to exclude from the response. Available options:

alerts: Excludes national watches, warnings, and advisories
environment: Excludes environmental risks
wildlife: Excludes wildlife risks
plants: Excludes plant risks
activity_intelligence: Excludes the AI-generated summary

profile

object

Information about who is going outside. This object is extensible - you can add custom fields beyond the standard ones listed below.

Show profile properties

profile.activity

string

The outdoor activity you plan to do (e.g., “hiking”, “camping”, “skiing”). This helps personalize the Activity Intelligence.

profile.age

integer

The age of the person doing the activity. Used to provide age-appropriate risk analysis in the Activity Intelligence.

profile.outdoor_experience

integer

Experience level with outdoor activities, from 0 (beginner) to 4 (expert).

profile.context

string

Any additional context that may be relevant for the forecast. This helps provide more personalized Activity Intelligence.

Example

curl -X POST "http://api.goes.health/v1/risks/overview/forecast" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "location": "37.7485,-119.5331",
    "options": {
      "length": "standard",
      "exclude": []
    },
    "profile": {
      "activity": "hiking",
      "age": 32,
      "outdoor_experience": 2,
      "context": "Planning a multi-day backpacking trip"
    }
  }'

Response

Both the GET and POST methods return the same response format. The POST method provides more personalized content in the Activity Intelligence field.

responseId

string

A unique identifier for this response. Use this ID if submitting feedback about the forecast.

activity_intelligence

string

AI-generated summary of the overall 48-hour forecast, personalized to your activity and experience level when using the POST method.

forecast

array

An array of 48 hourly forecast entries.

Show child attributes

time

string

ISO 8601 timestamp (UTC) representing the forecast hour.

risks

array

Consolidated risks for this hour.

Show child attributes

string

The unique identifier for the risk.

title

string

The human-readable title of the risk.

source

string

The source of this risk (“environment”, “wildlife”, or “plants”).

status

enum

The status of this risk assessment:

applicable: Risk is present and relevant for this location
not_applicable: Risk is not present or relevant for this location
unavailable: Risk data is unavailable for this location
error: An error occurred while assessing this risk

score

integer

A number from 0-3 representing the risk level or prevalence:

For environmental risks: risk level from 0 (None) to 3 (High)
For wildlife and plant risks: prevalence score from 0 (None) to 3 (High)

tips

array

A collection of 1-2 sentence strings with tips and recommendations.

summary

string

A 1-2 sentence summary of the tips and key information.

error

string

Error message describing what went wrong. Only present when status is error.

alerts

array

Active NOAA weather alerts for this hour (United States only).

{
  "responseId": "123e4567-e89b-12d3-a456-426614174000",
  "activity_intelligence": "For your backpacking trip, early morning conditions are ideal with low UV and minimal lightning risk. This is the perfect time to break camp and start your hike before temperatures rise.",
  "forecast": [
    {
      "time": "2024-06-27T00:00:00Z",
      "risks": [
        {
          "id": "sunburn",
          "title": "Sunburn",
          "source": "environment",
          "status": "applicable",
          "score": 2,
          "summary": "...",
          "tips": [
            "..."
          ]
        }
      ],
      "alerts": []
    }
  ]
}

Query Parameters

location

string

required

The latitude and longitude, formatted as {latitude},{longitude}.

options.length

enum<string>

default:standard

Controls the length of the forecast summary text for each hour.

Available options:

brief,

standard,

detailed

options.exclude

string

Comma-separated list of sections to exclude from the response. Options: alerts, environment, wildlife, plants, activity_intelligence

Response

200

application/json

A 48-hour forecast overview of risks with default settings.

The response is of type object.

Current Risks

Forecasted Risks

Other

Simple Request (GET)

Headers

Query Parameters

Example

Advanced Request (POST)

Headers

Body Parameters

Example

Response

Query Parameters

Response

Current Risks

Forecasted Risks

Other

​Simple Request (GET)

​Headers

​Query Parameters

​Example

​Advanced Request (POST)

​Headers

​Body Parameters

​Example

​Response

Query Parameters

Response

Simple Request (GET)

Headers

Query Parameters

Example

Advanced Request (POST)

Headers

Body Parameters

Example

Response