POST AI agent ready /v1/weather/current

Weather API - Current Conditions by City or Coordinates

Returns current weather data for a location specified by city name or latitude/longitude. The response includes temperature (with feels-like), humidity, precipitation, wind speed and direction, cloud cover, a numeric weather code, and a human-readable description.

Endpoint

Code examples

curl -X POST https://api.botoi.com/v1/weather/current \
  -H "Content-Type: application/json" \
  -d '{"city":"London","lat":51.5074,"lng":-0.1278}'

When to use this API

Dynamic content based on local weather

Personalize homepage banners or product recommendations based on the visitor's local weather. A retail site can promote umbrellas when it's raining or sunscreen during clear skies, increasing conversion rates with contextual relevance.

Logistics and delivery route planning

Check weather conditions along delivery routes before dispatching drivers. Flag routes with high winds or heavy precipitation so dispatchers can reroute or delay shipments to protect goods and driver safety.

IoT and smart home automation

Poll current weather data to trigger smart home actions. Close motorized blinds when cloud cover drops below 20%, activate sprinklers only when precipitation is zero, or adjust thermostat setpoints based on the feels-like temperature.

Frequently asked questions

Should I use city name or coordinates?

Either works. City name is convenient for user-facing inputs. Coordinates are more precise and avoid ambiguity when multiple cities share the same name (e.g., "Springfield" exists in over 30 US states).

What temperature unit is returned?

Temperatures are returned in Celsius by default. The unit field in the response confirms this. Convert to Fahrenheit client-side with the formula F = C * 9/5 + 32.

How often is the weather data updated?

Weather data refreshes every 15 minutes from upstream sources. For most applications, caching responses for 10-15 minutes on your side is safe and reduces API calls.

What does the weather_code field represent?

The weather_code is a numeric WMO weather interpretation code. Common values: 0 = clear sky, 1-3 = partly cloudy, 45/48 = fog, 51-67 = drizzle/rain, 71-77 = snow, 80-82 = rain showers, 95+ = thunderstorm. The description field provides the human-readable label.

What happens if neither city nor coordinates are provided?

The endpoint returns an error asking you to provide either a city name or a lat/lng pair. At least one location parameter is required.

Get your API key

Free tier includes 5 requests per minute with no credit card required. Upgrade for higher limits.