Skip to main content

​
Get Current Weather

Retrieve current weather conditions for a specified city.

​
Endpoint

GET /api/weather/current

​
Query Parameters

​
city
string
required
City name (e.g., “London”, “New York”, “Tokyo”)

​
Example Request

curl -X GET "https://rocks.rive.wtf/api/weather/current?city=London" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response Example

{
  "base": "stations",
  "clouds": {
    "all": 100
  },
  "cod": 200,
  "coord": {
    "lat": 51.5085,
    "lon": -0.1257
  },
  "dt": 1769733093,
  "id": 2643743,
  "main": {
    "feels_like": 271.86,
    "grnd_level": 987,
    "humidity": 92,
    "pressure": 991,
    "sea_level": 991,
    "temp": 276.95,
    "temp_max": 277.73,
    "temp_min": 276.1
  },
  "name": "London",
  "sys": {
    "country": "GB",
    "id": 2075535,
    "sunrise": 1769758927,
    "sunset": 1769791515,
    "type": 2
  },
  "timezone": 0,
  "visibility": 9000,
  "weather": [
    {
      "description": "overcast clouds",
      "icon": "04n",
      "id": 804,
      "main": "Clouds"
    }
  ],
  "wind": {
    "deg": 100,
    "gust": null,
    "speed": 7.72
  }
}

​
Response Fields

​
name
string
City name
​
coord
object
Geographic coordinates
  • lat - Latitude
  • lon - Longitude
​
main
object
Main weather parameters
  • temp - Temperature (Kelvin)
  • feels_like - Perceived temperature (Kelvin)
  • temp_min - Minimum temperature (Kelvin)
  • temp_max - Maximum temperature (Kelvin)
  • pressure - Atmospheric pressure (hPa)
  • humidity - Humidity percentage
  • sea_level - Atmospheric pressure at sea level (hPa)
  • grnd_level - Atmospheric pressure at ground level (hPa)
​
weather
array
Weather condition details
  • id - Weather condition ID
  • main - Weather parameter (Rain, Snow, Clouds, etc.)
  • description - Weather condition description
  • icon - Weather icon ID
​
wind
object
Wind information
  • speed - Wind speed (meter/sec)
  • deg - Wind direction (degrees)
  • gust - Wind gust speed (meter/sec)
​
clouds
object
Cloudiness information
  • all - Cloudiness percentage
​
sys
object
System data
  • country - Country code
  • sunrise - Sunrise time (Unix timestamp)
  • sunset - Sunset time (Unix timestamp)
​
visibility
number
Visibility in meters
​
dt
number
Data calculation time (Unix timestamp)

​
Get Weather Forecast

Retrieve weather forecast data for a specified city.

​
Endpoint

GET /api/weather/forecast

​
Query Parameters

​
city
string
required
City name (e.g., “London”, “New York”, “Tokyo”)
​
count
number
Number of forecast entries to return (default: 40, max: 40)

​
Example Request

curl -X GET "https://rocks.rive.wtf/api/weather/forecast?city=London&count=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response Example

{
  "city": {
    "coord": {
      "lat": 51.5085,
      "lon": -0.1257
    },
    "country": "GB",
    "id": 2643743,
    "name": "London",
    "population": 1000000,
    "sunrise": 1769758927,
    "sunset": 1769791515,
    "timezone": 0
  },
  "cnt": 5,
  "cod": "200",
  "list": [
    {
      "clouds": {
        "all": 100
      },
      "dt": 1769742000,
      "dt_txt": "2026-01-30 03:00:00",
      "main": {
        "feels_like": 272.95,
        "grnd_level": 986,
        "humidity": 90,
        "pressure": 991,
        "sea_level": 991,
        "temp": 277.0,
        "temp_max": 277.07,
        "temp_min": 277.0
      },
      "pop": 0.2,
      "sys": {
        "pod": "n"
      },
      "visibility": 10000,
      "weather": [
        {
          "description": "light rain",
          "icon": "10n",
          "id": 500,
          "main": "Rain"
        }
      ],
      "wind": {
        "deg": 117,
        "gust": 12.05,
        "speed": 5.21
      }
    }
  ],
  "message": 0.0
}

​
Response Fields

​
city
object
City information
  • name - City name
  • country - Country code
  • coord - Geographic coordinates (lat, lon)
  • population - City population
  • timezone - Timezone offset in seconds
  • sunrise - Sunrise time (Unix timestamp)
  • sunset - Sunset time (Unix timestamp)
​
cnt
number
Number of forecast entries returned
​
list
array
Array of forecast entries, each containing:
Temperature values are returned in Kelvin. To convert to Celsius: K - 273.15. To convert to Fahrenheit: (K - 273.15) × 9/5 + 32
Forecast data is available in 3-hour intervals. Use the count parameter to limit the number of forecast periods returned.

​
Use Cases

Weather Bots

Build Discord or Telegram weather bots

Travel Planning

Check weather before trips

Smart Home

Integrate with home automation

Mobile Apps

Add weather features to apps