worldweatheronline-com API

openapi: 3.1.0
info:
  title: worldweatheronline-com API
  version: '2026-10-31'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-10-31: 10 operation(s) read from 13 public documentation page(s) (each
    operation names its page in x-source). This is not the provider''s published contract; worldweatheronline-com has published no machine-readable
    contract that the pipeline could find. Engine: oss.'
  x-evidence-tiers:
    code-example: 6
    documentation: 4
    pages-with-code: 8
    pages-read: 13
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-10-31'
  x-generator: generate-contract-from-docs.py
  x-engine: oss
  x-sources:
  - https://www.worldweatheronline.com/weather-api/api/docs/bulk-api.aspx
  - https://www.worldweatheronline.com/weather-api/api/docs/search-api.aspx
  - https://www.worldweatheronline.com/weather-api/api/ski-weather-api.aspx
  - https://www.worldweatheronline.com/weather-api/api/marine-weather-api.aspx
  - https://www.worldweatheronline.com/weather-api/api/docs/ski-weather-api.aspx
  - https://www.worldweatheronline.com/weather-api/api/historical-weather-api.aspx
  - https://www.worldweatheronline.com/weather-api/api/docs/marine-weather-api.aspx
  - https://www.worldweatheronline.com/weather-api/api/docs/historical-weather-api.aspx
  - https://www.worldweatheronline.com/weather-api/api/local-city-town-weather-api.aspx
  - https://www.worldweatheronline.com/weather-api/api/historical-marine-weather-api.aspx
  - https://www.worldweatheronline.com/weather-api/api/docs/historical-marine-weather-api.aspx
  - https://www.worldweatheronline.com/weather-api/api/docs/astronomy-api.aspx
  - https://www.worldweatheronline.com/weather-api/api/docs/time-zone-api.aspx
servers:
- url: https://api.worldweatheronline.com
paths:
  /astronomy.ashx:
    get:
      operationId: get_astronomy_ashx
      tags:
      - Astronomy
      summary: Retrieve precise sunrise, sunset, moonrise, moonset, moon phase, and moon illumination data for any location and date.
      description: Returns solar and lunar data for a given location and date, including timezone information.
      x-source: https://www.worldweatheronline.com/weather-api/api/docs/astronomy-api.aspx
      parameters:
      - name: key
        in: query
        required: true
        schema:
          type: string
        description: Your API authentication key.
      - name: q
        in: query
        required: true
        schema:
          type: string
        description: The location for which to retrieve astronomy data. Accepts city name, postcode, zip, IP, or lat,lon.
      - name: date
        in: query
        required: true
        schema:
          type: string
        description: The date for which to retrieve astronomy data. Accepts today, tomorrow, or yyyy‑MM‑dd.
      - name: includelocation
        in: query
        required: false
        schema:
          type: string
        description: Whether to include the nearest_area block in the response. Set to yes to include location details.
      - name: format
        in: query
        required: false
        schema:
          type: string
        description: Output format. Supports xml (default), json, or csv.
      - name: show_comments
        in: query
        required: false
        schema:
          type: string
        description: When format=csv, controls whether comment header lines are included.
      - name: callback
        in: query
        required: false
        schema:
          type: string
        description: Wraps the JSON response in a named JavaScript callback function for JSONP.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAstronomyAshxResponse'
      x-evidence:
        kind: documentation
  /premium/v1/astronomy.ashx:
    get:
      operationId: get_premium_v1_astronomy_ashx
      tags:
      - Premium
      summary: GET /premium/v1/astronomy.ashx
      x-source: https://www.worldweatheronline.com/weather-api/api/docs/astronomy-api.aspx
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: httpie
        snippet: "HTTP \n http://api.worldweatheronline.com/premium/v1/astronomy.ashx "
  /premium/v1/marine.ashx:
    get:
      operationId: get_premium_v1_marine_ashx
      tags:
      - Premium
      summary: GET /premium/v1/marine.ashx
      x-source: https://www.worldweatheronline.com/weather-api/api/docs/bulk-api.aspx
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl --location 'http://api.worldweatheronline.com/premium/v1/marine.ashx'  --form 'key=\"YOUR_API_KEY\"'  --form 'q=\"51.5,-1.8;48.5,-4.2;43.3,5.4\"\
          '  --form 'format=\"json\"'  --form 'tide=\"yes\"' \n Limits & Constraints \n Constraint Value Notes \n Max locations per request \n\
          \ 10 \n Requests with more than 10 locations will be rejected. \n Quota consumption \n 1 per location \n A request for 5 locations deduc"
  /premium/v1/past-marine.ashx:
    get:
      operationId: get_premium_v1_past_marine_ashx
      tags:
      - Premium
      summary: Historical Marine Weather API
      description: Retrieve past marine, sailing and surfing weather data for a given latitude/longitude and date.
      x-source: https://www.worldweatheronline.com/weather-api/api/historical-marine-weather-api.aspx
      parameters:
      - name: key
        in: query
        required: true
        schema:
          type: string
        description: Your API key (required for authentication)
      - name: q
        in: query
        required: true
        schema:
          type: string
        description: Latitude and longitude of the location, formatted as lat,lng (e.g., 51.5,-0.12)
      - name: date
        in: query
        required: true
        schema:
          type: string
        description: Date of the historical record in YYYY-MM-DD format
      - name: format
        in: query
        required: false
        schema:
          type: string
        description: Desired output format (json, xml, csv, tab, jsonp)
      - name: tide
        in: query
        required: false
        schema:
          type: string
        description: Set to yes to include tide data
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPremiumV1PastMarineAshxResponse'
      x-evidence:
        kind: documentation
  /premium/v1/past-weather.ashx:
    get:
      operationId: get_premium_v1_past_weather_ashx
      tags:
      - Premium
      summary: Historical Weather API - Past Weather Data
      description: Retrieve historical weather data for a given location and date.
      x-source: https://www.worldweatheronline.com/weather-api/api/historical-weather-api.aspx
      parameters:
      - name: key
        in: query
        required: true
        schema:
          type: string
        description: Your API key.
      - name: q
        in: query
        required: true
        schema:
          type: string
        description: Location query (city name, postcode, zip, IP, IATA code, or lat,lon).
      - name: date
        in: query
        required: true
        schema:
          type: string
        description: 'Date for which to retrieve data (format: YYYY-MM-DD).'
      - name: tp
        in: query
        required: false
        schema:
          type: integer
        description: Time interval in hours (1, 3, 6, 12, 24).
      - name: format
        in: query
        required: false
        schema:
          type: string
        description: Response format (json, xml, csv, tab, jsonp).
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPremiumV1PastWeatherAshxResponse'
      x-evidence:
        kind: documentation
  /premium/v1/search.ashx:
    get:
      operationId: get_premium_v1_search_ashx
      tags:
      - Premium
      summary: GET /premium/v1/search.ashx
      x-source: https://www.worldweatheronline.com/weather-api/api/docs/search-api.aspx
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: httpie
        snippet: "HTTP \n http://api.worldweatheronline.com/premium/v1/search.ashx "
  /premium/v1/ski.ashx:
    get:
      operationId: get_premium_v1_ski_ashx
      tags:
      - Premium
      summary: Ski and Mountain Weather API provides multi‑elevation ski forecasts via a GET request.
      description: Returns ski‑specific and standard meteorological forecast data for up to 7 days in 24‑hour intervals for the supplied latitude/longitude
        location.
      x-source: https://www.worldweatheronline.com/weather-api/api/ski-weather-api.aspx
      parameters:
      - name: key
        in: query
        required: true
        schema:
          type: string
        description: Your API key (required).
      - name: q
        in: query
        required: true
        schema:
          type: string
        description: Latitude and longitude of the location as decimal degrees (e.g., 45.9763,7.6586).
      - name: format
        in: query
        required: false
        schema:
          type: string
        description: Response format (json, xml, jsonp).
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPremiumV1SkiAshxResponse'
      x-evidence:
        kind: documentation
  /premium/v1/tz.ashx:
    get:
      operationId: get_premium_v1_tz_ashx
      tags:
      - Premium
      summary: GET /premium/v1/tz.ashx
      x-source: https://www.worldweatheronline.com/weather-api/api/docs/time-zone-api.aspx
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: httpie
        snippet: "HTTP \n http://api.worldweatheronline.com/premium/v1/tz.ashx "
  /premium/v1/weather.ashx:
    get:
      operationId: get_premium_v1_weather_ashx
      tags:
      - Premium
      summary: GET /premium/v1/weather.ashx
      x-source: https://www.worldweatheronline.com/weather-api/api/docs/bulk-api.aspx
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl and Python examples below). \n POST \n http://api.worldweatheronline.com/premium/v1/weather.ashx \n Endpoints \n Copy "
    post:
      operationId: post_premium_v1_weather_ashx
      tags:
      - Premium
      summary: POST /premium/v1/weather.ashx
      x-source: https://www.worldweatheronline.com/weather-api/api/docs/bulk-api.aspx
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: javascript
        snippet: "fetch ( \n 'http://api.worldweatheronline.com/premium/v1/weather.ashx' , \n { method: 'POST' , body: form } \n)"
components:
  schemas:
    GetAstronomyAshxResponse:
      type: object
      properties:
        request.type:
          type: string
          description: The type of query that was matched, e.g. City, LatLon, IP, Postcode.
        request.query:
          type: string
          description: The resolved location string that was used to look up the data.
        nearest_area.areaName:
          type: string
          description: Name of the resolved city or town.
        nearest_area.country:
          type: string
          description: Country name.
        nearest_area.region:
          type: string
          description: State, province, or region name (where available).
        nearest_area.latitude:
          type: number
          description: Latitude of the resolved location in decimal degrees.
        nearest_area.longitude:
          type: number
          description: Longitude of the resolved location in decimal degrees.
        time_zone.localtime:
          type: string
          description: Current local date and time at the requested location (yyyy-MM-dd HH:mm).
        time_zone.utcOffset:
          type: number
          description: UTC offset in decimal hours (positive east of UTC, negative west).
        time_zone.zone:
          type: string
          description: IANA timezone name, e.g. Europe/London.
        time_zone.sunrise:
          type: string
          description: Time of sunrise at the location in 12‑hour format.
        time_zone.sunset:
          type: string
          description: Time of sunset at the location in 12‑hour format.
        time_zone.moonrise:
          type: string
          description: Time of moonrise at the location in 12‑hour format (or "No moonrise").
        time_zone.moonset:
          type: string
          description: Time of moonset at the location in 12‑hour format (or "No moonset").
        time_zone.moon_phase:
          type: string
          description: Descriptive moon phase name.
        time_zone.moon_illumination:
          type: integer
          description: Percentage of the moon's visible surface that is illuminated (0‑100).
    GetPremiumV1PastMarineAshxResponse:
      type: object
      properties:
        significant_wave_height:
          type: number
          description: Significant wave height in metres
        swell_height:
          type: number
          description: Swell height in metres
        swell_period:
          type: number
          description: Swell period in seconds
        swell_direction:
          type: number
          description: Swell direction in degrees
        sea_surface_temperature:
          type: number
          description: Sea surface temperature in °C
        water_temperature:
          type: number
          description: Water temperature in °C (and optionally °F)
        tide_height:
          type: number
          description: Tide height in metres (optional)
        tide_type:
          type: string
          description: Tide type – High or Low (optional)
        temperature:
          type: number
          description: Air temperature in °C
        wind_speed:
          type: number
          description: Wind speed (mph, km/h, etc.)
        wind_direction:
          type: string
          description: Wind direction (16‑point compass)
        precipitation:
          type: number
          description: Precipitation/rainfall in mm
        humidity:
          type: number
          description: Relative humidity in %
        visibility:
          type: number
          description: Visibility in km
        pressure:
          type: number
          description: Atmospheric pressure in mb
        cloud_cover:
          type: number
          description: Cloud cover in %
        wind_chill:
          type: number
          description: Wind chill / feels like temperature in °C
        dew_point:
          type: number
          description: Dew point in °C
        heat_index:
          type: number
          description: Heat index in °C
    GetPremiumV1PastWeatherAshxResponse:
      type: object
      properties:
        date:
          type: string
          description: Date of the record.
        sunrise:
          type: string
          description: Sunrise time (local).
        sunset:
          type: string
          description: Sunset time (local).
        maxtempC:
          type: string
          description: Maximum temperature in Celsius.
        maxtempF:
          type: string
          description: Maximum temperature in Fahrenheit.
        mintempC:
          type: string
          description: Minimum temperature in Celsius.
        mintempF:
          type: string
          description: Minimum temperature in Fahrenheit.
        hourly.time:
          type: string
          description: Time of the interval.
        hourly.tempC:
          type: string
          description: Temperature in Celsius.
        hourly.tempF:
          type: string
          description: Temperature in Fahrenheit.
        hourly.windchillC:
          type: string
          description: Wind chill in Celsius.
        hourly.windchillF:
          type: string
          description: Wind chill in Fahrenheit.
        hourly.dewpointC:
          type: string
          description: Dew point in Celsius.
        hourly.dewpointF:
          type: string
          description: Dew point in Fahrenheit.
        hourly.heatIndexC:
          type: string
          description: Heat index in Celsius.
        hourly.heatIndexF:
          type: string
          description: Heat index in Fahrenheit.
        hourly.windspeedMiles:
          type: string
          description: Wind speed in miles per hour.
        hourly.windspeedKmph:
          type: string
          description: Wind speed in km/h.
        hourly.windspeedKts:
          type: string
          description: Wind speed in knots.
        hourly.windspeedMs:
          type: string
          description: Wind speed in meters per second.
        hourly.winddir16Point:
          type: string
          description: Wind direction as 16‑point compass.
        hourly.weatherCode:
          type: string
          description: Standardised weather condition code.
        hourly.weatherDesc:
          type: string
          description: Human‑readable weather description.
        hourly.weatherIconUrl:
          type: string
          description: URL to weather condition icon.
        hourly.precipMM:
          type: string
          description: Precipitation in millimetres.
        hourly.precipInches:
          type: string
          description: Precipitation in inches.
        hourly.humidity:
          type: string
          description: Relative humidity percentage.
        hourly.visibility:
          type: string
          description: Visibility in km.
        hourly.visibilityMiles:
          type: string
          description: Visibility in miles.
        hourly.pressureMb:
          type: string
          description: Atmospheric pressure in millibars.
        hourly.pressureInches:
          type: string
          description: Atmospheric pressure in inches of mercury.
        hourly.cloudcover:
          type: string
          description: Cloud cover percentage.
    GetPremiumV1SkiAshxResponse:
      type: object
      properties:
        date:
          type: string
          description: Date of the forecast period.
        max_temp_c:
          type: number
          description: Maximum temperature (°C).
        min_temp_c:
          type: number
          description: Minimum temperature (°C).
        sunrise:
          type: string
          description: Sunrise time (local).
        sunset:
          type: string
          description: Sunset time (local).
        moonrise:
          type: string
          description: Moonrise time (local).
        moonset:
          type: string
          description: Moonset time (local).
        hourly_temp_c:
          type: number
          description: Hourly temperature (°C).
        wind_speed_mph:
          type: number
          description: Wind speed (mph).
        wind_speed_kph:
          type: number
          description: Wind speed (km/h).
        wind_dir:
          type: string
          description: Wind direction (16‑point compass).
        weather_code:
          type: string
          description: Standardised weather condition code.
        weather_desc:
          type: string
          description: Weather description text.
        weather_icon_url:
          type: string
          description: URL to weather condition icon.
        precip_mm:
          type: number
          description: Precipitation / rainfall (mm).
        humidity:
          type: number
          description: Relative humidity (%).
        visibility_km:
          type: number
          description: Visibility (km).
        pressure_mb:
          type: number
          description: Atmospheric pressure (mb).
        cloudcover:
          type: number
          description: Cloud cover (%).
        chanceofrain:
          type: number
          description: Probability of rain (%).
        chanceofsnow:
          type: number
          description: Probability of snow (%).
        chanceofthunder:
          type: number
          description: Probability of thunder (%).
        chanceofcloud:
          type: number
          description: Probability of cloud (%).
        chanceofsunshine:
          type: number
          description: Probability of sunshine (%).
        chanceoffreeze:
          type: number
          description: Probability of temperature falling below freezing (%).
        top_snowfall_cm:
          type: number
          description: Expected snowfall at top elevation (cm).
        middle_snowfall_cm:
          type: number
          description: Expected snowfall at middle elevation (cm).
        bottom_snowfall_cm:
          type: number
          description: Expected snowfall at bottom elevation (cm).
        top_freezing_level_m:
          type: number
          description: Freezing level at top elevation (metres above sea level).
        middle_freezing_level_m:
          type: number
          description: Freezing level at middle elevation (metres above sea level).
        bottom_freezing_level_m:
          type: number
          description: Freezing level at bottom elevation (metres above sea level).
        top_chance_of_snow:
          type: number
          description: Chance of snow at top elevation (%).
        middle_chance_of_snow:
          type: number
          description: Chance of snow at middle elevation (%).
        bottom_chance_of_snow:
          type: number
          description: Chance of snow at bottom elevation (%).
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
security:
- apiKey: []
tags:
- name: Astronomy
- name: Premium