> ## 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 Overview

> Returns an 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 comprehensive overview of all risks and alerts for a location, combining environmental risks, wildlife risks, plant risks, and national weather alerts. 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 Activity Intelligence text. 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?location=37.7485,-119.5331" \
  -H "Authorization: Bearer YOUR_API_KEY"

# With options
curl "http://api.goes.health/v1/risks/overview?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 Activity Intelligence text. 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 Activity Intelligence
    </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 when summarizing.
    </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 risk summarization. This helps provide more personalized recommendations.
    </ParamField>
  </Expandable>
</ParamField>

## Response

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

<ResponseField name="activity_intelligence" type="string">
  An AI-generated summary paragraph that consolidates all risks and alerts, personalized to your activity and experience level.
</ResponseField>

<ResponseField name="risks" type="array">
  A comprehensive array of all risks from environmental, wildlife, and plant sources.

  <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">
  An array of active NOAA weather alerts for the United States.

  <Expandable title="child attributes">
    <ResponseField name="event" type="string">
      The type of weather event. Example: `Severe Thunderstorm Warning`.
    </ResponseField>

    <ResponseField name="severity" type="string">
      The severity level of the alert as specified by NOAA. Example: `Severe`.
    </ResponseField>

    <ResponseField name="senderName" type="string">
      The NWS office that issued the alert. Example: `NWS Riverton WY`.
    </ResponseField>

    <ResponseField name="headline" type="string">
      A complete headline of the alert including timing and issuing office.
    </ResponseField>

    <ResponseField name="description" type="string">
      Detailed description of the weather event, including specific hazards, source of information, and impacts.
    </ResponseField>

    <ResponseField name="instruction" type="string">
      Safety instructions and recommended actions for the public.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example

```bash theme={null}
curl -X POST "http://api.goes.health/v1/risks/overview" \
  -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": "First time hiker"
    }
  }'
```

## Response

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

```json theme={null}
{
  "responseId": "123e4567-e89b-12d3-a456-426614174000",
  "activity_intelligence": "For your Half Dome hike today, be prepared for significant elevation gain and exposed terrain. The combination of high altitude, bear activity, and lightning risk requires careful planning. Start early and monitor weather conditions closely.",
  "risks": [
    {
      "id": "high-altitude",
      "title": "High Altitude",
      "source": "environment",
      "status": "applicable",
      "score": 3,
      "summary": "...",
      "tips": [
        "..."
      ]
    },
    {
      "id": "sunburn",
      "title": "Sun Exposure",
      "source": "environment",
      "status": "applicable",
      "score": 2,
      "summary": "...",
      "tips": [
        "..."
      ]
    },
    {
      "id": "lightning",
      "title": "Lightning",
      "source": "environment",
      "status": "applicable",
      "score": 1,
      "summary": "...",
      "tips": [
        "..."
      ]
    },
    {
      "id": "bears",
      "title": "Bears",
      "source": "wildlife",
      "status": "applicable",
      "score": 2,
      "summary": "...",
      "tips": [
        "..."
      ]
    },
    {
      "id": "frostbite",
      "title": "Frostbite",
      "source": "environment",
      "status": "not_applicable",
      "score": 0,
      "summary": "...",
      "tips": [
        "..."
      ]
    },
    {
      "id": "poison-sumac",
      "title": "Poison Sumac",
      "source": "plants",
      "status": "unavailable"
    }
  ],
  "alerts": []
}
```


## OpenAPI

````yaml GET /v1/risks/overview
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:
    get:
      description: >-
        Returns an 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 Activity Intelligence text.
          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 basic overview of all risks with default settings.
          content:
            application/json:
              schema:
                type: object
                required:
                  - responseId
                  - activity_intelligence
                  - risks
                properties:
                  responseId:
                    type: string
                    format: uuid
                    description: A unique identifier for this response
                  activity_intelligence:
                    type: string
                    description: >-
                      An AI-generated summary paragraph that consolidates all
                      risks and alerts
                  risks:
                    type: array
                    description: >-
                      A comprehensive array of all risks from environmental,
                      wildlife, and plant sources
                    items:
                      $ref: '#/components/schemas/OverviewRisk'
                  alerts:
                    type: array
                    description: >-
                      An array of active NOAA weather alerts for the United
                      States
                    items:
                      type: object
                      required:
                        - event
                        - severity
                        - senderName
                        - headline
                        - description
                        - instruction
                      properties:
                        event:
                          type: string
                          description: The type of weather event
                          example: Severe Thunderstorm Warning
                        severity:
                          type: string
                          description: The severity level of the alert as specified by NOAA
                          example: Severe
                        senderName:
                          type: string
                          description: The NWS office that issued the alert
                          example: NWS Los Angeles CA
                        headline:
                          type: string
                          description: >-
                            A complete headline of the alert including timing
                            and issuing office
                          example: >-
                            Severe Thunderstorm Warning issued August 15 at
                            2:30PM PDT until August 15 at 5:00PM PDT by NWS Los
                            Angeles CA
                        description:
                          type: string
                          description: >-
                            Detailed description of the weather event, including
                            specific hazards, source of information, and impacts
                          example: >-
                            At 2:30 PM PDT, a severe thunderstorm was located
                            over the Santa Monica Mountains, moving east at 25
                            mph. HAZARD...60 mph wind gusts and penny size hail.
                            SOURCE...Radar indicated.
                        instruction:
                          type: string
                          description: >-
                            Safety instructions and recommended actions for the
                            public
                          example: >-
                            For your protection move to an interior room on the
                            lowest floor of a building. Torrential rainfall is
                            occurring with this storm, and may lead to flash
                            flooding.
              example:
                responseId: 123e4567-e89b-12d3-a456-426614174000
                activity_intelligence: >-
                  For your Half Dome hike today, be prepared for significant
                  elevation gain and exposed terrain. The combination of high
                  altitude, bear activity, and lightning risk requires careful
                  planning. Start early and monitor weather conditions closely.
                risks:
                  - id: sunburn
                    title: Sunburn
                    source: environment
                    status: applicable
                    score: 2
                    summary: <string>
                    tips:
                      - <string>
                alerts: []
        '400':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    OverviewRisk:
      oneOf:
        - $ref: '#/components/schemas/EnvironmentalOverviewRisk'
        - $ref: '#/components/schemas/WildlifePlantOverviewRisk'
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
    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'.

````