openapi: 3.1.0
info:
  title: WeatherAPI.com Alerts Geo API
  description: 'WeatherAPI.com provides real-time, forecast, historical, marine, future, astronomy, air quality, pollen, sports, IP lookup, timezone, and geolocation data via a JSON/XML REST API. Trusted by 850,000+ developers worldwide. Average response time ~200ms.


    ## Authentication

    All endpoints require an API key passed as the `key` query parameter.


    ## Base URL

    `https://api.weatherapi.com/v1`


    ## Location Query (`q` parameter)

    Accepts: city name, lat/lon decimal, US zip, UK postcode, Canada postal code, METAR code (`metar:EGLL`), IATA airport code (`iata:DXB`), IP lookup (`auto:ip`), IPv4/IPv6 address, or location ID (`id:2801268`).


    ## Plans

    - **Free**: 100K calls/month, 3-day forecast, 1-day history

    - **Starter**: $7/mo — 3M calls, 7-day forecast, 7-day history

    - **Pro+**: $25/mo — 5M calls, 300-day future, 365-day history

    - **Business**: $65/mo — 10M calls, evapotranspiration

    - **Enterprise**: Custom — 15-min interval, pollen history, wind@100m, SLA'
  version: 1.0.2
  contact:
    name: WeatherAPI.com Support
    url: https://www.weatherapi.com/contact.aspx
  license:
    name: Commercial / Non-Commercial
    url: https://www.weatherapi.com/terms.aspx
  x-logo:
    url: https://cdn.weatherapi.com/v4/images/weatherapi_logo.png
  x-last-validated: '2026-05-28'
  x-generated-from: provider-openapi
servers:
- url: https://api.weatherapi.com/v1
  description: Production (HTTPS)
- url: http://api.weatherapi.com/v1
  description: Production (HTTP)
security:
- ApiKeyAuth: []
tags:
- name: Geo
  description: Location, IP lookup, timezone, astronomy
paths:
  /search.json:
    get:
      tags:
      - Geo
      summary: WeatherAPI Search / Autocomplete Locations
      description: Returns matching cities and towns as an array of Location objects. Useful for building autocomplete location pickers.
      operationId: searchLocations
      parameters:
      - $ref: '#/components/parameters/key'
      - name: q
        in: query
        required: true
        description: Partial city name, postcode, or coordinates to search.
        schema:
          type: string
          example: lond
        example: lond
      responses:
        '200':
          description: List of matching locations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SearchLocation'
              examples:
                SearchLocations200Example:
                  summary: Default searchLocations 200 response
                  x-microcks-default: true
                  value:
                  - id: 2643743
                    name: London
                    region: City of London, Greater London
                    country: United Kingdom
                    lat: 51.5074
                    lon: -0.1278
                    url: sample value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /ip.json:
    get:
      tags:
      - Geo
      summary: WeatherAPI IP Lookup
      description: Returns geolocation and timezone data for a given IPv4 or IPv6 address. Pass `auto:ip` to auto-detect the caller's IP.
      operationId: ipLookup
      parameters:
      - $ref: '#/components/parameters/key'
      - name: q
        in: query
        required: true
        description: IPv4, IPv6 address, or `auto:ip` for caller's IP.
        schema:
          type: string
          example: auto:ip
        example: auto:ip
      responses:
        '200':
          description: IP geolocation data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpLookupResponse'
              examples:
                IpLookup200Example:
                  summary: Default ipLookup 200 response
                  x-microcks-default: true
                  value:
                    ip: sample value
                    type: ipv4
                    continent_code: EGLL
                    continent_name: EU
                    country_code: United Kingdom
                    country_name: United Kingdom
                    is_eu: false
                    geoname_id: sample value
                    city: sample value
                    region: City of London, Greater London
                    lat: 51.5074
                    lon: -0.1278
                    tz_id: Europe/London
                    localtime_epoch: 1748441400
                    localtime: 2026-05-28 15:30
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /timezone.json:
    get:
      tags:
      - Geo
      summary: WeatherAPI Time Zone
      description: Returns the local time and timezone information for a given location.
      operationId: getTimezone
      parameters:
      - $ref: '#/components/parameters/key'
      - $ref: '#/components/parameters/q'
      responses:
        '200':
          description: Timezone data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimezoneResponse'
              examples:
                GetTimezone200Example:
                  summary: Default getTimezone 200 response
                  x-microcks-default: true
                  value:
                    location:
                      name: London
                      region: City of London, Greater London
                      country: United Kingdom
                      lat: 51.5074
                      lon: -0.1278
                      tz_id: Europe/London
                      localtime_epoch: 1748441400
                      localtime: 2026-05-28 15:30
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /astronomy.json:
    get:
      tags:
      - Geo
      summary: WeatherAPI Astronomy
      description: Returns sunrise, sunset, moonrise, moonset, moon phase, and moon illumination for a given location and date.
      operationId: getAstronomy
      parameters:
      - $ref: '#/components/parameters/key'
      - $ref: '#/components/parameters/q'
      - name: dt
        in: query
        required: true
        description: Date in yyyy-MM-dd format.
        schema:
          type: string
          format: date
          example: '2026-03-20'
        example: '2026-03-20'
      responses:
        '200':
          description: Astronomy data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AstronomyResponse'
              examples:
                GetAstronomy200Example:
                  summary: Default getAstronomy 200 response
                  x-microcks-default: true
                  value:
                    location:
                      name: London
                      region: City of London, Greater London
                      country: United Kingdom
                      lat: 51.5074
                      lon: -0.1278
                      tz_id: Europe/London
                      localtime_epoch: 1748441400
                      localtime: 2026-05-28 15:30
                    astronomy:
                      astro:
                        sunrise: 05:30 AM
                        sunset: 08:45 PM
                        moonrise: 10:15 PM
                        moonset: 06:42 AM
                        moon_phase: Waxing Crescent
                        moon_illumination: 35.0
                        is_moon_up: 1
                        is_sun_up: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    q:
      name: q
      in: query
      required: true
      description: 'Location query. Accepts: city name, lat/lon, US zip, UK postcode, Canada postal code, METAR code (metar:EGLL), IATA (iata:DXB), auto:ip, IPv4/IPv6, or location ID (id:2801268).'
      schema:
        type: string
        example: London
    key:
      name: key
      in: query
      required: true
      description: Your WeatherAPI.com API key.
      schema:
        type: string
        example: YOUR_API_KEY
  schemas:
    Location:
      type: object
      description: Location metadata returned with every weather response.
      properties:
        name:
          type: string
          description: Location name
          example: London
        region:
          type: string
          description: Region or state
          example: City of London, Greater London
        country:
          type: string
          description: Country name
          example: United Kingdom
        lat:
          type: number
          format: float
          description: Latitude
          example: 51.5074
        lon:
          type: number
          format: float
          description: Longitude
          example: -0.1278
        tz_id:
          type: string
          description: IANA timezone ID, e.g. Europe/London
          example: Europe/London
        localtime_epoch:
          type: integer
          description: Local time as Unix epoch
          example: 1748441400
        localtime:
          type: string
          description: Local date and time string
          example: 2026-05-28 15:30
    SearchLocation:
      type: object
      properties:
        id:
          type: integer
          example: 2643743
        name:
          type: string
          example: London
        region:
          type: string
          example: City of London, Greater London
        country:
          type: string
          example: United Kingdom
        lat:
          type: number
          example: 51.5074
        lon:
          type: number
          example: -0.1278
        url:
          type: string
          description: URL-safe location slug
          example: sample value
    AstronomyResponse:
      type: object
      properties:
        location:
          $ref: '#/components/schemas/Location'
        astronomy:
          type: object
          properties:
            astro:
              $ref: '#/components/schemas/AstroElement'
    TimezoneResponse:
      type: object
      properties:
        location:
          $ref: '#/components/schemas/Location'
    IpLookupResponse:
      type: object
      properties:
        ip:
          type: string
          example: sample value
        type:
          type: string
          enum:
          - ipv4
          - ipv6
          example: ipv4
        continent_code:
          type: string
          example: EGLL
        continent_name:
          type: string
          example: EU
        country_code:
          type: string
          example: United Kingdom
        country_name:
          type: string
          example: United Kingdom
        is_eu:
          type: boolean
          example: false
        geoname_id:
          type: string
          example: sample value
        city:
          type: string
          example: sample value
        region:
          type: string
          example: City of London, Greater London
        lat:
          type: number
          example: 51.5074
        lon:
          type: number
          example: -0.1278
        tz_id:
          type: string
          example: Europe/London
        localtime_epoch:
          type: integer
          example: 1748441400
        localtime:
          type: string
          example: 2026-05-28 15:30
    AstroElement:
      type: object
      properties:
        sunrise:
          type: string
          example: 05:30 AM
        sunset:
          type: string
          example: 08:45 PM
        moonrise:
          type: string
          example: 10:15 PM
        moonset:
          type: string
          example: 06:42 AM
        moon_phase:
          type: string
          example: Waxing Crescent
        moon_illumination:
          type: number
          example: 35.0
        is_moon_up:
          type: integer
          example: 1
        is_sun_up:
          type: integer
          example: 1
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: WeatherAPI error code
            message:
              type: string
      example:
        error:
          code: 1006
          message: No location found matching parameter 'q'
  responses:
    Unauthorized:
      description: Unauthorized — API key missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request — invalid parameter or location not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: key
      description: API key obtained from https://www.weatherapi.com/my/. Pass as `?key=YOUR_API_KEY` query parameter.
externalDocs:
  description: Official WeatherAPI.com Documentation
  url: https://www.weatherapi.com/docs/