Get Forecast Overview

Returns a 48-hour forecast overview of all risks for a given location with default settings.

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

id · 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.

responseId · string<uuid> · required

A unique identifier for this response

activity_intelligence · string · required

AI-generated summary of the overall 48-hour forecast

forecast · object[] · required

48 entries (hourly) each containing risk details and alerts.

Show child attributes