NewConnect Claude, Gemini, ChatGPT, and other AI agents to API Ninjas via our MCP server →

Weather API

The Weather API provides the latest weather, forecast, and historical weather data for any city or geographic location in the world.

Available endpoints:

Online
(4.7)

From 6,675 users

700+

Applications using this API

API Status

Online - All Systems Operational

API Response Times

Average
P50
P75
P90
P95
281ms315ms370ms524ms1154ms

Didn't find what you were looking for? Suggest an improvement

3 endpoints

https://api.api-ninjas.com/v1/weather

Get current weather, wind speed and direction, humidity, and temperature data by city, ZIP code, or geolocation coordinates (latitude/longitude).

Parameters

One of the following parameter combinations must be provided:

  • lat and lon
  • city, state (optional), and country (optional)
  • lat  optional

    Latitude of desired location.

  • lon  optional

    Longitude of desired location.

  • zip  optional Premium only

    5 digit Zip code (United States only)

  • city  optional Premium only

    City name.

  • state  optional Premium only

    US state (for United States cities only).

  • country  optional Premium only

    Country name.

Headers

  • X-Api-Key  required

    API Key associated with your account.

Response

A JSON object with the following fields or an error if the request is unsuccessful.

  • temp

    Current temperature in Celsius.

  • feels_like

    What the temperature feels like in Celsius.

  • humidity

    Current humidity percentage.

  • cloud_pct

    Cloud cover percentage.

  • min_temp

    Minimum temperature in Celsius.

  • max_temp

    Maximum temperature in Celsius.

  • wind_speed

    Wind speed in meters per second.

  • wind_degrees

    Wind direction in degrees.

  • sunrise

    Sunrise time in Unix timestamp.

  • sunset

    Sunset time in Unix timestamp.

  • weather

    Primary weather category, such as Rain, Snow, or Clouds; null if unavailable.

  • weather_code

    Detailed provider condition ID. Unknown IDs are preserved; null if no valid ID is available.

  • weather_description

    Description of the primary condition. Use this as the icon alternative text.

  • is_day

    Whether it is daytime at the weather location. True for day, false for night, or null when unavailable. This is independent of your application theme.

  • weather_icon

    Stable icon name, such as rain-light or clear-night. Unknown conditions use the unknown icon.

  • weather_icon_url

    Public HTTPS URL of the SVG icon for a light interface.

  • weather_icon_url_dark

    Public HTTPS URL of the SVG icon for a dark interface.

  • weather_icon_png_url

    Public HTTPS URL of the 128-pixel transparent PNG for a light interface.

  • weather_icon_png_url_dark

    Public HTTPS URL of the 128-pixel transparent PNG for a dark interface.

  • weather_conditions

    All simultaneous conditions, in provider order. Each has the weather, weather_code, weather_description, is_day, weather_icon, and four URL fields above. The first is the primary condition. An empty array means condition data was unavailable.

Live Demo

Live demo · no API key required
Query parameters
lat
lon
city Premium only
state Premium only
country Premium only

Get a free API key to get started — no credit card required.

Headers
X-Api-KeyLog in or sign up to get your API key
GET
https://api.api-ninjas.com/v1/weather?lat=51.5074&lon=-0.1278
Sample response
{
"weather": "Clouds",
"weather_code": 803,
"weather_description": "broken clouds",
"is_day": true,
"weather_icon": "broken-clouds-day",
"weather_icon_url": "https://api-ninjas-data.s3.us-west-2.amazonaws.com/weather-icons/v1/svg/broken-clouds-day.svg",
"weather_icon_url_dark": "https://api-ninjas-data.s3.us-west-2.amazonaws.com/weather-icons/v1/dark/svg/broken-clouds-day.svg",
"weather_icon_png_url": "https://api-ninjas-data.s3.us-west-2.amazonaws.com/weather-icons/v1/png/128/broken-clouds-day.png",
"weather_icon_png_url_dark": "https://api-ninjas-data.s3.us-west-2.amazonaws.com/weather-icons/v1/dark/png/128/broken-clouds-day.png",
"weather_conditions": [
{
"weather": "Clouds",
"weather_code": 803,
"weather_description": "broken clouds",
"is_day": true,
"weather_icon": "broken-clouds-day",
"weather_icon_url": "https://api-ninjas-data.s3.us-west-2.amazonaws.com/weather-icons/v1/svg/broken-clouds-day.svg",
"weather_icon_url_dark": "https://api-ninjas-data.s3.us-west-2.amazonaws.com/weather-icons/v1/dark/svg/broken-clouds-day.svg",
"weather_icon_png_url": "https://api-ninjas-data.s3.us-west-2.amazonaws.com/weather-icons/v1/png/128/broken-clouds-day.png",
"weather_icon_png_url_dark": "https://api-ninjas-data.s3.us-west-2.amazonaws.com/weather-icons/v1/dark/png/128/broken-clouds-day.png"
}
],
"wind_speed": 5.66,
"wind_degrees": 210,
"temp": 7,
"humidity": 87,
"sunset": 1615658463,
"min_temp": 7,
"cloud_pct": 75,
"feels_like": 2,
"sunrise": 1615616341,
"max_temp": 8
}

Code Examples

curl -X GET "https://api.api-ninjas.com/v1/weather?city=london" \ -H "X-Api-Key: YOUR_API_KEY"

If your programming language is not listed in the Code Example above, you can still make API calls by using a HTTP request library written in your programming language and following the above documentation.

https://api.api-ninjas.com/v1/weatherforecast

Returns a 5-day weather forecast in 3-hour intervals for a given city.

Parameters

One of the following parameter combinations must be provided:

  • lat  required

    Latitude of desired location.

  • lon  required

    Longitude of desired location.

  • zip  required Premium only

    5 digit Zip code (United States only)

  • city  required Premium only

    City name.

  • state  optional Premium only

    US state (for United States cities only).

  • country  optional Premium only

    Country name.

Headers

  • X-Api-Key  required

    API Key associated with your account.

Response

A JSON array of objects with the same fields as Weather Response, or an error if the request is unsuccessful.

Live Demo

Live demo · no API key required
Query parameters
lat
lon

Get a free API key to get started — no credit card required.

Headers
X-Api-KeyLog in or sign up to get your API key
GET
https://api.api-ninjas.com/v1/weatherforecast?lat=51.5074&lon=-0.1278
Sample response
[
{
"weather": "Clouds",
"weather_code": 803,
"weather_description": "broken clouds",
"is_day": true,
"weather_icon": "broken-clouds-day",
"weather_icon_url": "https://api-ninjas-data.s3.us-west-2.amazonaws.com/weather-icons/v1/svg/broken-clouds-day.svg",
"weather_icon_url_dark": "https://api-ninjas-data.s3.us-west-2.amazonaws.com/weather-icons/v1/dark/svg/broken-clouds-day.svg",
"weather_icon_png_url": "https://api-ninjas-data.s3.us-west-2.amazonaws.com/weather-icons/v1/png/128/broken-clouds-day.png",
"weather_icon_png_url_dark": "https://api-ninjas-data.s3.us-west-2.amazonaws.com/weather-icons/v1/dark/png/128/broken-clouds-day.png",
"weather_conditions": [
{
"weather": "Clouds",
"weather_code": 803,
"weather_description": "broken clouds",
"is_day": true,
"weather_icon": "broken-clouds-day",
"weather_icon_url": "https://api-ninjas-data.s3.us-west-2.amazonaws.com/weather-icons/v1/svg/broken-clouds-day.svg",
"weather_icon_url_dark": "https://api-ninjas-data.s3.us-west-2.amazonaws.com/weather-icons/v1/dark/svg/broken-clouds-day.svg",
"weather_icon_png_url": "https://api-ninjas-data.s3.us-west-2.amazonaws.com/weather-icons/v1/png/128/broken-clouds-day.png",
"weather_icon_png_url_dark": "https://api-ninjas-data.s3.us-west-2.amazonaws.com/weather-icons/v1/dark/png/128/broken-clouds-day.png"
}
],
"timestamp": 1740247200,
"temp": 13,
"feels_like": 12,
"humidity": 70,
"min_temp": 10,
"max_temp": 13,
"cloud_pct": 75,
"wind_speed": 2.36,
"wind_degrees": 231
},
"..."
]

Code Examples

curl -X GET "https://api.api-ninjas.com/v1/weatherforecast?lat=51.5074&lon=-0.1278" \ -H "X-Api-Key: YOUR_API_KEY"

Premium only

https://api.api-ninjas.com/v1/weathericons

Returns the complete weather icon catalog: 74 icon names, 592 public image URLs, and mappings for all 55 supported condition codes. Every icon includes light and dark SVGs and transparent PNGs at 64, 128, and 256 pixels.

This endpoint requires a Premium subscription. The individual icon URLs in current weather and forecast responses remain available with those endpoints.

Parameters

This endpoint does not require any parameters.

Headers

X-Api-Key (required): an API key associated with a paid subscription. Anonymous demo access is not available.

Response

A JSON object with the following fields, or an error if authentication, subscription, or quota checks fail.

  • version

    Version of the icon collection.

  • icon_count

    Number of distinct icon names (74), each available in both themes.

  • file_count

    Total number of image URLs across both themes and all formats (592).

  • condition_count

    Number of mapped provider condition codes (55).

  • icons

    Complete list of icons. Each entry includes icon (stable name), description, weather_codes, phase, type, light, and dark. Each theme contains svg and png URLs; png is keyed by 64, 128, and 256.

  • conditions

    Complete condition mapping. Each entry contains code, description, and icons, which maps day, night, and neutral to stable icon names.

phase is day, night, neutral (time unspecified), or any (the same icon at all times). type is core, extension, or fallback. Extension and fallback icons have an empty weather_codes array; extensions do not imply that the API currently detects those phenomena.

Choose the theme to match your interface and the phase to match the weather location. Preserve the condition description alongside the icon, especially at small sizes.

Live Demo

Live demo · premium API key required

Get a free API key to get started — no credit card required.

Headers
X-Api-KeyLog in or sign up to get your API key
GET
https://api.api-ninjas.com/v1/weathericons
Sample response
{
"version": "1.0.0",
"icon_count": 74,
"file_count": 592,
"condition_count": 55,
"icons": [
{
"icon": "storm-rain-light",
"description": "Storm · light rain",
"weather_codes": [
200
],
"phase": "any",
"type": "core",
"light": {
"svg": "https://api-ninjas-data.s3.us-west-2.amazonaws.com/weather-icons/v1/svg/storm-rain-light.svg",
"png": {
"64": "https://api-ninjas-data.s3.us-west-2.amazonaws.com/weather-icons/v1/png/64/storm-rain-light.png",
"128": "https://api-ninjas-data.s3.us-west-2.amazonaws.com/weather-icons/v1/png/128/storm-rain-light.png",
"256": "https://api-ninjas-data.s3.us-west-2.amazonaws.com/weather-icons/v1/png/256/storm-rain-light.png"
}
},
"dark": {
"svg": "https://api-ninjas-data.s3.us-west-2.amazonaws.com/weather-icons/v1/dark/svg/storm-rain-light.svg",
"png": {
"64": "https://api-ninjas-data.s3.us-west-2.amazonaws.com/weather-icons/v1/dark/png/64/storm-rain-light.png",
"128": "https://api-ninjas-data.s3.us-west-2.amazonaws.com/weather-icons/v1/dark/png/128/storm-rain-light.png",
"256": "https://api-ninjas-data.s3.us-west-2.amazonaws.com/weather-icons/v1/dark/png/256/storm-rain-light.png"
}
}
},
"..."
],
"conditions": [
{
"code": 200,
"description": "Storm · light rain",
"icons": {
"day": "storm-rain-light",
"night": "storm-rain-light",
"neutral": "storm-rain-light"
}
},
"..."
]
}

Code Examples

curl -X GET "https://api.api-ninjas.com/v1/weathericons" \ -H "X-Api-Key: YOUR_API_KEY"

Frequently Asked Questions

  • Yes, but you must have a premium subscription. Commercial use of the Weather API is not permitted on the free tier. See our pricing page to choose a plan that fits your needs.
  • Sign up for a free account to instantly get your API key, then pass it in the X-Api-Key header on every request. The documentation above includes ready-to-run examples in cURL, Python, JavaScript, Node.js, and more.
  • Your API requests will simply be denied once you hit your monthly quota — you will never be charged more than the plan you signed up for. To increase your quota, you can upgrade your plan any time on our pricing page.
  • The API responds with a standard HTTP status code and a JSON error message describing the problem. See our error codes reference for the full list of codes and how to resolve each one, or contact support if you need help.
  • Yes. Current weather and forecast responses include weather_icon_url and weather_icon_url_dark for SVG icons, plus weather_icon_png_url and weather_icon_png_url_dark for transparent 128-pixel PNGs. The Premium-only /v1/weathericons endpoint returns all 592 image URLs across 74 icon names, both themes, and every available size, with mappings for all 55 supported condition codes.
  • The /v1/weather endpoint accepts either lat and lon coordinates, or a city name with optional state (US only) and country parameters; note that the city, state, country, and zip parameters are premium-only, as shown on our pricing page. If you only have a place name and need coordinates first, pair it with our Geocoding API.
  • All temperature fields (temp, feels_like, min_temp, max_temp) are returned in Celsius, wind_speed is in meters per second, and wind_degrees gives wind direction in degrees, while humidity and cloud_pct are percentages. For other location-based data sources, see our full API catalog.
  • Yes, the /v1/weather response includes sunrise and sunset times, both given as Unix timestamps. To convert these to a location's local time, you can combine the response with our Timezone API.
  • The /v1/weatherforecast endpoint returns a 5-day forecast in 3-hour intervals as a JSON array, with each entry containing the same fields as the current weather response (such as temp, humidity, and wind_speed); on the free tier it requires lat and lon. If a request returns an error instead, check our error codes reference.

Explore API integration use cases for recommended APIs and workflow examples.