api-ninjas-com

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.

Documentation GitHub OpenAPI

Operations 3

GET /v1/weather Get current weather data #

GET /v1/weatherforecast Get a 5-day weather forecast in 3-hour intervals #

GET /v1/weathericons Get the complete weather icon catalog (Premium only) #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

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.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/api-ninjas-com:api-ninjas-com-weather-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API 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.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

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