# Guide

The River Gauge API provides river water level observations, station metadata, and flood stage information.

For full request and response field details, see [River Gauge Parameters](/developers/river-gauge/parameters).

:::note{title="Base URLs"}

- **Production:** api.accuweather.com
- **Development:** apidev.accuweather.com

Examples below use the production host. Swap in apidev.accuweather.com for development.

:::

| Endpoint | Description |
|---|---|
| [Observations](#observations) | River gauge observation data by country, bounding box, or all |
| [Stations](#stations) | Station metadata by country, bounding box, or all |
| [River status](#river-status) | River flood status definitions |

---

## Observations

Search observation data using any one of three methods:

- [Search by country code or by country code and administrative area.](#observations-by-country-code-or-by-country-code-and-administrative-area)
- [Search by a bounding box, defined by latitude and longitude values.](#observations-by-bounding-box)
- [Return all available observations.](#all-available-observations)

## Observations by country code or by country code and administrative area

```
https://{baseUrl}/rivers/{version}/{country code}/{admin code}/observations{.format}?apikey={API key}&metric={boolean}&includeunits={boolean}
```

### Example

```
https://api.accuweather.com/rivers/v1/US/VA/observations.json?apikey={API key}&metric=true&includeunits=true
```

```json
[
    {
        "observation": {
            "dateTime": "2024-04-09T15:30:00-04:00",
            "height": {
                "value": 1.3,
                "unit": "m"
            }
        },
        "categories": {
            "action": {
                "value": 1.8,
                "unit": "m"
            },
            "flood": {
                "value": 3.7,
                "unit": "m"
            },
            "moderate": {
                "value": 4.6,
                "unit": "m"
            },
            "major": {
                "value": 5.5,
                "unit": "m"
            },
            "lowThreshold": null
        },
        "id": "AFRV2",
        "location": {
            "name": "Alexandria",
            "countryCode": "US",
            "adminCode": "VA"
        },
        "waterBody": "Four Mile Run",
        "status": {
            "name": "No Flooding",
            "colorHex": "#00ff00"
        }
    },
    {...}
]
```

## Observations by bounding box

```
https://{baseUrl}/rivers/{version}/observations{.format}?apikey={API key}&upperleft={lat,lon}&lowerright={lat,lon}&metric={boolean}&includeunits={boolean}
```

### Example

```
https://api.accuweather.com/rivers/v1/observations.geojson?apikey={API key}&upperleft=61,-148&lowerright=20,-70&metric=false
```

```json
{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "coordinates": [
                    -97.7933349609375,
                    30.221111297607422
                ],
                "type": "Point"
            },
            "properties": {
                "observation": {
                    "dateTime": "2024-04-09T19:30:00+00:00",
                    "height": 0.6
                },
                "categories": {
                    "action": null,
                    "flood": 4,
                    "moderate": 4.3,
                    "major": 5.5,
                    "lowThreshold": null
                },
                "id": "AAIT2",
                "location": {
                    "name": "Manchaca Road at Austin",
                    "countryCode": "US",
                    "adminCode": "TX"
                },
                "waterBody": "Williamson Creek",
                "status": {
                    "name": "No Flooding",
                    "colorHex": "#00ff00"
                }
            }
        },
        {...}
    ]
}
```

## All available observations

```
https://{baseUrl}/rivers/{version}/observations{.format}?apikey={API key}&metric={boolean}&includeunits={boolean}
```

### Example

```
https://api.accuweather.com/rivers/v1/observations?apikey={API key}
```

```json
[
    {
        "observation": {
            "dateTime": "2024-04-09T19:30:00+00:00",
            "height": 2
        },
        "categories": {
            "action": null,
            "flood": 13,
            "moderate": 14,
            "major": 18,
            "lowThreshold": null
        },
        "id": "AAIT2",
        "location": {
            "name": "Manchaca Road at Austin",
            "countryCode": "US",
            "adminCode": "TX"
        },
        "waterBody": "Williamson Creek",
        "status": {
            "name": "No Flooding",
            "colorHex": "#00ff00"
        }
    },
    {...}
]
```

## Stations
```
https://{baseUrl}/rivers/{version}/{country code}/{admin code}/stations{.format}?apikey={API key}
```

### Example

```
https://api.accuweather.com/rivers/v1/US/VA/stations.geojson?apikey={API key}
```

```json
{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "coordinates": [
                    -81.98332977294922,
                    36.68583297729492
                ],
                "type": "Point"
            },
            "properties": {
                "id": "ABDV2",
                "goesId": "24415608",
                "dcpOwner": "TENNVA",
                "hydrologicServiceArea": "MRX",
                "location": {
                    "name": "ABINGTON",
                    "countryCode": "US",
                    "adminCode": "VA"
                }
            }
        },
        {...}
    ]
}
```

## River status
```
https://{baseUrl}/rivers/{version}/statuses{.format}?apikey={API key}
```

### Example

```
https://api.accuweather.com/rivers/v1/statuses.json?apikey={API key}
```

```json
[
    {
        "id": "action",
        "name": "Near Flood Stage",
        "colorHex": "#ffff00"
    },
    {
        "id": "low_threshold",
        "name": "At or Below Low Water Threshold",
        "colorHex": "#906320"
    },
    {
        "id": "major",
        "name": "Major Flooding",
        "colorHex": "#cc33ff"
    },
    {...}
]
```