api-ninjas-com Weather API
The Weather API provides the latest weather, forecast, and historical weather data for any city or geographic location in the world.
The Weather API provides the latest weather, forecast, and historical weather data for any city or geographic location in the world.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/api-ninjas-com:api-ninjas-com-weather-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Ninjas Weather API
description: 'Combined OpenAPI specification for every API Ninjas endpoint. Requests go to https://api.api-ninjas.com with an `X-Api-Key` header; get a free key at https://api-ninjas.com/register. Human-readable docs: https://api-ninjas.com/api. Index for LLMs: https://api-ninjas.com/llms.txt.'
version: 1.0.0
contact:
name: API Ninjas
url: https://api-ninjas.com
license:
name: Proprietary
servers:
- url: https://api.api-ninjas.com
description: API Ninjas Production
security:
- ApiKeyAuth: []
tags:
- name: Weather
description: The Weather API provides the latest weather, forecast, and historical weather data for any city or geographic location in the world.
paths:
/v1/weather:
get:
summary: Get current weather data
description: 'Get current weather, wind speed and direction, humidity, and temperature data by city, ZIP code, or geolocation coordinates (latitude/longitude). One of the following parameter combinations must be provided: lat and lon; or city, state (optional), and country (optional).'
operationId: getCurrentWeather
parameters:
- name: lat
in: query
required: false
schema:
type: string
description: Latitude of desired location.
- name: lon
in: query
required: false
schema:
type: string
description: Longitude of desired location.
- name: zip
in: query
required: false
schema:
type: string
description: 5 digit Zip code (United States only). Premium subscribers only.
- name: city
in: query
required: false
schema:
type: string
description: City name. Premium subscribers only.
- name: state
in: query
required: false
schema:
type: string
description: US state (for United States cities only). Premium subscribers only.
- name: country
in: query
required: false
schema:
type: string
description: Country name. Premium subscribers only.
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/WeatherResponse'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
security:
- ApiKeyAuth: []
tags:
- Weather
/v1/weatherforecast:
get:
summary: Get a 5-day weather forecast in 3-hour intervals
description: 'Returns a 5-day weather forecast in 3-hour intervals for a given city. One of the following parameter combinations must be provided: lat and lon; zip; or city, state (optional), and country (optional).'
operationId: getWeatherForecast
parameters:
- name: lat
in: query
required: false
schema:
type: string
description: Latitude of desired location.
- name: lon
in: query
required: false
schema:
type: string
description: Longitude of desired location.
- name: zip
in: query
required: false
schema:
type: string
description: 5 digit Zip code (United States only). Premium subscribers only.
- name: city
in: query
required: false
schema:
type: string
description: City name. Premium subscribers only.
- name: state
in: query
required: false
schema:
type: string
description: US state (for United States cities only). Premium subscribers only.
- name: country
in: query
required: false
schema:
type: string
description: Country name. Premium subscribers only.
responses:
'200':
description: A JSON array of weather forecast entries with the same fields as the Weather Response.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ForecastResponse'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
security:
- ApiKeyAuth: []
tags:
- Weather
/v1/weathericons:
get:
summary: Get the complete weather icon catalog (Premium only)
description: Returns every light/dark SVG and 64/128/256-pixel PNG URL for the 74 icons, plus all 55 condition-code mappings. Requires an authenticated paid API Ninjas subscription; normal Weather API quotas apply. No anonymous demo access. No parameters required.
operationId: getWeatherIcons
parameters: []
responses:
'200':
description: The complete catalog of 592 public image URLs.
content:
application/json:
schema:
$ref: '#/components/schemas/WeatherIconCatalog'
'400':
description: Missing or invalid API key, Premium subscription required, or quota exceeded.
security:
- ApiKeyAuth: []
tags:
- Weather
components:
schemas:
ForecastResponse:
allOf:
- $ref: '#/components/schemas/WeatherResponse'
- type: object
properties:
timestamp:
type: integer
description: Forecast timestamp in Unix seconds (UTC).
WeatherResponse:
type: object
properties:
wind_speed:
type: number
description: Wind speed in meters per second.
wind_degrees:
type: integer
description: Wind direction in degrees.
temp:
type: integer
description: Current temperature in Celsius.
humidity:
type: integer
description: Current humidity percentage.
cloud_pct:
type: integer
description: Cloud cover percentage.
sunset:
type: integer
description: Sunset time in Unix timestamp.
min_temp:
type: integer
description: Minimum temperature in Celsius.
max_temp:
type: integer
description: Maximum temperature in Celsius.
feels_like:
type: integer
description: What the temperature feels like in Celsius.
sunrise:
type: integer
description: Sunrise time in Unix timestamp.
weather:
type:
- string
- 'null'
description: Primary weather category, such as Rain, Snow, or Clouds.
weather_code:
type:
- integer
- 'null'
description: Detailed provider condition ID. Unknown IDs are preserved.
weather_description:
type: string
description: Description of the primary condition. Use this as the icon alternative text.
is_day:
type:
- boolean
- 'null'
description: Whether it is daytime at the weather location. True for day, false for night.
weather_icon:
type: string
description: Stable icon name, such as rain-light or clear-night. Unknown conditions use the unknown icon.
weather_icon_url:
type: string
format: uri
description: Public HTTPS URL of the SVG icon for a light interface.
weather_icon_url_dark:
type: string
format: uri
description: Public HTTPS URL of the SVG icon for a dark interface.
weather_icon_png_url:
type: string
format: uri
description: Public HTTPS URL of the 128-pixel transparent PNG for a light interface.
weather_icon_png_url_dark:
type: string
format: uri
description: Public HTTPS URL of the 128-pixel transparent PNG for a dark interface.
weather_conditions:
type: array
description: 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.
items:
$ref: '#/components/schemas/WeatherCondition'
WeatherIconTheme:
type: object
required:
- svg
- png
properties:
svg:
type: string
format: uri
png:
type: object
required:
- '64'
- '128'
- '256'
properties:
'64':
type: string
format: uri
'128':
type: string
format: uri
'256':
type: string
format: uri
WeatherCondition:
type: object
required:
- weather
- weather_code
- weather_description
- is_day
- weather_icon
- weather_icon_url
- weather_icon_url_dark
- weather_icon_png_url
- weather_icon_png_url_dark
properties:
weather:
type:
- string
- 'null'
description: Primary weather category, such as Rain, Snow, or Clouds.
weather_code:
type:
- integer
- 'null'
description: Detailed provider condition ID. Unknown IDs are preserved.
weather_description:
type: string
description: Description of the primary condition. Use this as the icon alternative text.
is_day:
type:
- boolean
- 'null'
description: Whether it is daytime at the weather location. True for day, false for night.
weather_icon:
type: string
description: Stable icon name, such as rain-light or clear-night. Unknown conditions use the unknown icon.
weather_icon_url:
type: string
format: uri
description: Public HTTPS URL of the SVG icon for a light interface.
weather_icon_url_dark:
type: string
format: uri
description: Public HTTPS URL of the SVG icon for a dark interface.
weather_icon_png_url:
type: string
format: uri
description: Public HTTPS URL of the 128-pixel transparent PNG for a light interface.
weather_icon_png_url_dark:
type: string
format: uri
description: Public HTTPS URL of the 128-pixel transparent PNG for a dark interface.
WeatherIconConditionMapping:
type: object
required:
- code
- description
- icons
properties:
code:
type: integer
description:
type: string
icons:
type: object
required:
- day
- night
- neutral
properties:
day:
type: string
description: Stable icon name.
night:
type: string
description: Stable icon name.
neutral:
type: string
description: Stable icon name.
WeatherIconCatalog:
type: object
required:
- version
- icon_count
- file_count
- condition_count
- icons
- conditions
properties:
version:
type: string
icon_count:
type: integer
example: 74
file_count:
type: integer
example: 592
condition_count:
type: integer
example: 55
icons:
type: array
items:
$ref: '#/components/schemas/WeatherIcon'
conditions:
type: array
items:
$ref: '#/components/schemas/WeatherIconConditionMapping'
WeatherIcon:
type: object
required:
- icon
- description
- weather_codes
- phase
- type
- light
- dark
properties:
icon:
type: string
description:
type: string
weather_codes:
type: array
items:
type: integer
description: Empty for extensions and the fallback.
phase:
type: string
enum:
- day
- night
- neutral
- any
type:
type: string
enum:
- core
- extension
- fallback
light:
$ref: '#/components/schemas/WeatherIconTheme'
dark:
$ref: '#/components/schemas/WeatherIconTheme'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-Api-Key
externalDocs:
description: API Ninjas documentation
url: https://api-ninjas.com/api