> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goes.health/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Forecast Overview

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

<Note type="warning">
  **Coming Soon** — This endpoint is under development and will be available at a future date.
</Note>

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

<ParamField header="Authorization" type="string" required>
  Your API key for authentication. Format: `Bearer YOUR_API_KEY`
</ParamField>

### Query Parameters

<ParamField query="location" type="string" required>
  The latitude and longitude for the location to check, formatted as `{latitude},{longitude}`.
</ParamField>

<ParamField query="options" type="object">
  Configuration options that control how the response is built.

  <Expandable title="options properties">
    <ParamField query="options.length" type="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
    </ParamField>

    <ParamField query="options.exclude" type="string">
      Comma-separated list of sections to exclude from the response. Options: `alerts`, `environment`, `wildlife`, `plants`, `activity_intelligence`
    </ParamField>
  </Expandable>
</ParamField>

### Example

```bash theme={null}
# 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

<ParamField header="Authorization" type="string" required>
  Your API key for authentication. Format: `Bearer YOUR_API_KEY`
</ParamField>

### Body Parameters

<ParamField body="location" type="string" required>
  The latitude and longitude for the location to check, formatted as `{latitude},{longitude}`.
</ParamField>

<ParamField body="options" type="object">
  Configuration options that control how the response is built.

  <Expandable title="options properties">
    <ParamField body="options.length" type="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
    </ParamField>

    <ParamField body="options.exclude" type="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
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="profile" type="object">
  Information about who is going outside. This object is extensible - you can add custom fields beyond the standard ones listed below.

  <Expandable title="profile properties">
    <ParamField body="profile.activity" type="string">
      The outdoor activity you plan to do (e.g., "hiking", "camping", "skiing"). This helps personalize the Activity Intelligence.
    </ParamField>

    <ParamField body="profile.age" type="integer">
      The age of the person doing the activity. Used to provide age-appropriate risk analysis in the Activity Intelligence.
    </ParamField>

    <ParamField body="profile.outdoor_experience" type="integer">
      Experience level with outdoor activities, from 0 (beginner) to 4 (expert).
    </ParamField>

    <ParamField body="profile.context" type="string">
      Any additional context that may be relevant for the forecast. This helps provide more personalized Activity Intelligence.
    </ParamField>
  </Expandable>
</ParamField>

### Example

```bash theme={null}
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.

<ResponseField name="responseId" type="string">
  A unique identifier for this response. Use this ID if submitting feedback about the forecast.
</ResponseField>

<ResponseField name="activity_intelligence" type="string">
  AI-generated summary of the overall 48-hour forecast, personalized to your activity and experience level when using the POST method.
</ResponseField>

<ResponseField name="forecast" type="array">
  An array of 48 hourly forecast entries.

  <Expandable title="child attributes">
    <ResponseField name="time" type="string">
      ISO 8601 timestamp (UTC) representing the forecast hour.
    </ResponseField>

    <ResponseField name="risks" type="array">
      Consolidated risks for this hour.

      <Expandable title="child attributes">
        <ResponseField name="id" type="string">
          The unique identifier for the risk.
        </ResponseField>

        <ResponseField name="title" type="string">
          The human-readable title of the risk.
        </ResponseField>

        <ResponseField name="source" type="string">
          The source of this risk ("environment", "wildlife", or "plants").
        </ResponseField>

        <ResponseField name="status" type="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
        </ResponseField>

        <ResponseField name="score" type="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)
        </ResponseField>

        <ResponseField name="tips" type="array">
          A collection of 1-2 sentence strings with tips and recommendations.
        </ResponseField>

        <ResponseField name="summary" type="string">
          A 1-2 sentence summary of the tips and key information.
        </ResponseField>

        <ResponseField name="error" type="string">
          Error message describing what went wrong. Only present when status is `error`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="alerts" type="array">
      Active NOAA weather alerts for this hour (United States only).
    </ResponseField>
  </Expandable>
</ResponseField>

```json theme={null}
{
  "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": []
    }
  ]
}
```


## OpenAPI

````yaml GET /v1/risks/overview/forecast
openapi: 3.1.0
info:
  title: GOES Health API
  description: API for accessing outdoor health risk data.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.goes.health
security: []
paths:
  /v1/risks/overview/forecast:
    get:
      description: >-
        Returns a 48-hour forecast overview of all risks for a given location
        with default settings.
      parameters:
        - name: location
          in: query
          description: The latitude and longitude, formatted as `{latitude},{longitude}`.
          required: true
          schema:
            type: string
            pattern: ^-?\d+(\.\d+)?,-?\d+(\.\d+)?$
          example: 37.7485,-119.5331
        - name: options.length
          in: query
          description: Controls the length of the forecast summary text for each hour.
          required: false
          schema:
            type: string
            enum:
              - brief
              - standard
              - detailed
            default: standard
        - name: options.exclude
          in: query
          description: >-
            Comma-separated list of sections to exclude from the response.
            Options: `alerts`, `environment`, `wildlife`, `plants`,
            `activity_intelligence`
          required: false
          schema:
            type: string
          example: alerts,wildlife
      responses:
        '200':
          description: A 48-hour forecast overview of risks with default settings.
          content:
            application/json:
              schema:
                type: object
                required:
                  - responseId
                  - activity_intelligence
                  - forecast
                properties:
                  responseId:
                    type: string
                    format: uuid
                    description: A unique identifier for this response
                  activity_intelligence:
                    type: string
                    description: AI-generated summary of the overall 48-hour forecast
                  forecast:
                    type: array
                    description: >-
                      48 entries (hourly) each containing risk details and
                      alerts.
                    items:
                      $ref: '#/components/schemas/OverviewForecastEntry'
        '400':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    OverviewForecastEntry:
      type: object
      required:
        - time
        - risks
      properties:
        time:
          type: string
          format: date-time
          description: ISO 8601 timestamp for the forecast hour
        risks:
          type: array
          items:
            $ref: '#/components/schemas/OverviewRisk'
        alerts:
          type: array
          description: Any active NOAA weather alerts for this hour.
          items:
            type: object
            required:
              - event
              - severity
              - senderName
              - headline
              - description
              - instruction
            properties:
              event:
                type: string
              severity:
                type: string
              senderName:
                type: string
              headline:
                type: string
              description:
                type: string
              instruction:
                type: string
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
    OverviewRisk:
      oneOf:
        - $ref: '#/components/schemas/EnvironmentalOverviewRisk'
        - $ref: '#/components/schemas/WildlifePlantOverviewRisk'
    EnvironmentalOverviewRisk:
      type: object
      required:
        - id
        - title
        - source
        - status
      properties:
        id:
          type: string
          description: The unique identifier for the environmental risk
          example: sunburn
        title:
          type: string
          description: The human-readable title of the environmental risk
          example: Sunburn
        source:
          type: string
          enum:
            - environment
          description: The source of this risk
          example: environment
        status:
          type: string
          enum:
            - applicable
            - not_applicable
            - unavailable
            - error
          description: The status of this risk assessment
        score:
          type: integer
          minimum: 0
          maximum: 3
          description: >-
            A number from 0-3 representing the risk level (0: None, 1: Low, 2:
            Medium, 3: High).
          example: 2
        summary:
          type: string
          description: A 1-2 sentence summary of the tips and key information.
          example: <string>
        tips:
          type: array
          items:
            type: string
          description: A collection of 1-2 sentence strings with tips and recommendations.
        error:
          type: string
          description: >-
            Error message describing what went wrong. Only present when status
            is 'error'.
    WildlifePlantOverviewRisk:
      type: object
      required:
        - id
        - title
        - source
        - status
      properties:
        id:
          type: string
          description: The unique identifier for the wildlife or plant risk
          example: bears
        title:
          type: string
          description: The human-readable title of the wildlife or plant risk
          example: Bears
        source:
          type: string
          enum:
            - wildlife
            - plants
          description: The source of this risk
          example: wildlife
        status:
          type: string
          enum:
            - applicable
            - not_applicable
            - unavailable
            - error
          description: The status of this risk assessment
        score:
          type: integer
          minimum: 0
          maximum: 3
          description: 'The prevalence score (0: None, 1: Low, 2: Medium, 3: High).'
        summary:
          type: string
          description: A 1-2 sentence summary of the tips and key information.
          example: <string>
        tips:
          type: array
          items:
            type: string
          description: A collection of 1-2 sentence strings with tips and recommendations.
        error:
          type: string
          description: >-
            Error message describing what went wrong. Only present when status
            is 'error'.

````