Tomorrow.io Weather API

openapi: 3.0.3
info:
  title: Tomorrow.io Weather API
  description: >-
    Unified Tomorrow.io v4 HTTP API for weather and climate intelligence.
    Combines realtime observations, forecast timelines (minutely, hourly, daily,
    current), historical data up to 20 years, weather along a route, raster map
    tiles, plus management surfaces for Locations, Insights, Alerts, and Events.
  version: 4.0.1
  contact:
    name: Tomorrow.io Support
    url: https://www.tomorrow.io/support/
  license:
    name: Tomorrow.io Terms of Service
    url: https://www.tomorrow.io/terms-of-service/
  x-generated-from: documentation
  x-last-validated: '2026-05-30'
servers:
- url: https://api.tomorrow.io/v4
  description: Tomorrow.io v4 production API
security:
- apiKeyQuery: []
tags:
- name: Realtime
  description: Current-conditions snapshot for a single location.
- name: Forecast
  description: Hourly and daily forecast timelines via a simple GET interface.
- name: Timelines
  description: Advanced multi-step (minutely / hourly / daily / current) forecast and historical timelines.
- name: Historical
  description: Historical weather data for a point or polygon, up to 20 years back.
- name: Climate
  description: 30-year climate normals for a location.
- name: Routes
  description: Weather along a polyline / list of waypoints with arrival-time interpolation.
- name: Map Tiles
  description: Raster tile endpoint for weather field overlays.
- name: Locations
  description: CRUD over monitored point / polygon / polyline locations with tags.
- name: Insights
  description: Define threshold rules over weather fields to detect business-significant events.
- name: Events
  description: Query events matching insights at a location or buffered geometry.
- name: Alerts
  description: Persistent alerts linked to one or more locations with webhook delivery.
paths:
  /weather/realtime:
    get:
      operationId: getRealtimeWeather
      summary: Tomorrow.io Get Realtime Weather
      description: Returns the current observed weather for a single location.
      tags:
      - Realtime
      parameters:
      - name: location
        in: query
        required: true
        description: Place name, latlong array as `lat,lng`, GeoJSON, or a saved location ID.
        schema:
          type: string
        example: 42.3478,-71.0466
      - name: units
        in: query
        required: false
        description: Unit system for returned values.
        schema:
          type: string
          enum:
          - metric
          - imperial
          default: metric
        example: metric
      responses:
        '200':
          description: Realtime weather snapshot.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealtimeWeatherResponse'
              examples:
                GetRealtimeWeather200Example:
                  summary: Default getRealtimeWeather 200 response
                  x-microcks-default: true
                  value:
                    data:
                      time: '2026-05-30T13:00:00Z'
                      values:
                        temperature: 21.2
                        temperatureApparent: 20.4
                        humidity: 64.0
                        dewPoint: 13.4
                        windSpeed: 3.1
                        windDirection: 220
                        windGust: 6.2
                        pressureSeaLevel: 1013.2
                        pressureSurfaceLevel: 1010.5
                        precipitationIntensity: 0.0
                        precipitationProbability: 5
                        precipitationType: 0
                        cloudCover: 12
                        cloudBase: 1.5
                        cloudCeiling: 2.4
                        visibility: 16
                        weatherCode: 1000
                        uvIndex: 6
                        uvHealthConcern: 2
                        epaIndex: 42
                        epaHealthConcern: 1
                        epaPrimaryPollutant: 0
                        particulateMatter25: 8.4
                        particulateMatter10: 14.1
                        pollutantO3: 28
                        pollutantNO2: 11
                        pollutantCO: 0.4
                        pollutantSO2: 1
                        treeIndex: 2
                        grassIndex: 1
                        weedIndex: 1
                        fireIndex: 8.2
                        solarGHI: 480
                        solarDIF: 120
                        solarDIR: 360
                        moonPhase: 3
                        hailBinary: 0
                    location:
                      lat: 42.3478
                      lon: -71.0466
                      name: Cambridge, MA
                      type: place
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /weather/forecast:
    get:
      operationId: getWeatherForecast
      summary: Tomorrow.io Get Weather Forecast
      description: Returns hourly and daily forecast timelines for a single location.
      tags:
      - Forecast
      parameters:
      - name: location
        in: query
        required: true
        description: Place name, latlong array, GeoJSON, or saved location ID.
        schema:
          type: string
        example: new york
      - name: timesteps
        in: query
        required: false
        description: Comma-separated forecast resolutions.
        schema:
          type: array
          items:
            type: string
            enum:
            - 1h
            - 1d
            - current
          default:
          - 1h
          - 1d
        example: 1h,1d
      - name: units
        in: query
        required: false
        schema:
          type: string
          enum:
          - metric
          - imperial
          default: metric
      responses:
        '200':
          description: Forecast timelines.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForecastResponse'
              examples:
                GetWeatherForecast200Example:
                  summary: Default getWeatherForecast 200 response
                  x-microcks-default: true
                  value:
                    timelines:
                      hourly:
                      - startTime: '2026-05-30T13:00:00Z'
                        values:
                          temperature: 21.2
                          temperatureApparent: 20.4
                          humidity: 64.0
                          dewPoint: 13.4
                          windSpeed: 3.1
                          windDirection: 220
                          windGust: 6.2
                          pressureSeaLevel: 1013.2
                          pressureSurfaceLevel: 1010.5
                          precipitationIntensity: 0.0
                          precipitationProbability: 5
                          precipitationType: 0
                          cloudCover: 12
                          cloudBase: 1.5
                          cloudCeiling: 2.4
                          visibility: 16
                          weatherCode: 1000
                          uvIndex: 6
                          uvHealthConcern: 2
                          epaIndex: 42
                          epaHealthConcern: 1
                          epaPrimaryPollutant: 0
                          particulateMatter25: 8.4
                          particulateMatter10: 14.1
                          pollutantO3: 28
                          pollutantNO2: 11
                          pollutantCO: 0.4
                          pollutantSO2: 1
                          treeIndex: 2
                          grassIndex: 1
                          weedIndex: 1
                          fireIndex: 8.2
                          solarGHI: 480
                          solarDIF: 120
                          solarDIR: 360
                          moonPhase: 3
                          hailBinary: 0
                      daily:
                      - startTime: '2026-05-30T13:00:00Z'
                        values:
                          temperature: 21.2
                          temperatureApparent: 20.4
                          humidity: 64.0
                          dewPoint: 13.4
                          windSpeed: 3.1
                          windDirection: 220
                          windGust: 6.2
                          pressureSeaLevel: 1013.2
                          pressureSurfaceLevel: 1010.5
                          precipitationIntensity: 0.0
                          precipitationProbability: 5
                          precipitationType: 0
                          cloudCover: 12
                          cloudBase: 1.5
                          cloudCeiling: 2.4
                          visibility: 16
                          weatherCode: 1000
                          uvIndex: 6
                          uvHealthConcern: 2
                          epaIndex: 42
                          epaHealthConcern: 1
                          epaPrimaryPollutant: 0
                          particulateMatter25: 8.4
                          particulateMatter10: 14.1
                          pollutantO3: 28
                          pollutantNO2: 11
                          pollutantCO: 0.4
                          pollutantSO2: 1
                          treeIndex: 2
                          grassIndex: 1
                          weedIndex: 1
                          fireIndex: 8.2
                          solarGHI: 480
                          solarDIF: 120
                          solarDIR: 360
                          moonPhase: 3
                          hailBinary: 0
                    location:
                      lat: 1.0
                      lon: 1.0
                      name: example
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /timelines:
    get:
      operationId: getTimelines
      summary: Tomorrow.io Get Timelines
      description: Basic GET form of the Timelines endpoint. Returns one or more timesteps for a single location.
      tags:
      - Timelines
      parameters:
      - name: location
        in: query
        required: true
        schema:
          type: string
        description: Latlong, place name, GeoJSON, or saved location ID.
        example: 42.3478,-71.0466
      - name: fields
        in: query
        required: true
        description: Comma-separated list of weather data fields to return.
        schema:
          type: array
          items:
            type: string
        example: temperature,humidity,windSpeed
      - name: startTime
        in: query
        required: false
        schema:
          type: string
          default: now
        example: now
      - name: endTime
        in: query
        required: false
        schema:
          type: string
          default: nowPlus6h
        example: nowPlus6h
      - name: timesteps
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - 1m
            - 5m
            - 15m
            - 30m
            - 1h
            - 1d
            - current
        example: 1h
      - name: units
        in: query
        required: false
        schema:
          type: string
          enum:
          - metric
          - imperial
          default: metric
      - name: timezone
        in: query
        required: false
        schema:
          type: string
          default: UTC
        example: America/New_York
      responses:
        '200':
          description: Timeline response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimelinesResponse'
              examples:
                GetTimelines200Example:
                  summary: Default getTimelines 200 response
                  x-microcks-default: true
                  value:
                    data:
                      timelines:
                      - timestep: 1h
                        startTime: '2026-05-30T13:00:00Z'
                        endTime: '2026-05-30T13:00:00Z'
                        intervals:
                        - startTime: '2026-05-30T13:00:00Z'
                          values:
                            temperature: 21.2
                            temperatureApparent: 20.4
                            humidity: 64.0
                            dewPoint: 13.4
                            windSpeed: 3.1
                            windDirection: 220
                            windGust: 6.2
                            pressureSeaLevel: 1013.2
                            pressureSurfaceLevel: 1010.5
                            precipitationIntensity: 0.0
                            precipitationProbability: 5
                            precipitationType: 0
                            cloudCover: 12
                            cloudBase: 1.5
                            cloudCeiling: 2.4
                            visibility: 16
                            weatherCode: 1000
                            uvIndex: 6
                            uvHealthConcern: 2
                            epaIndex: 42
                            epaHealthConcern: 1
                            epaPrimaryPollutant: 0
                            particulateMatter25: 8.4
                            particulateMatter10: 14.1
                            pollutantO3: 28
                            pollutantNO2: 11
                            pollutantCO: 0.4
                            pollutantSO2: 1
                            treeIndex: 2
                            grassIndex: 1
                            weedIndex: 1
                            fireIndex: 8.2
                            solarGHI: 480
                            solarDIF: 120
                            solarDIR: 360
                            moonPhase: 3
                            hailBinary: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: postTimelines
      summary: Tomorrow.io Post Timelines
      description: Advanced POST form of Timelines accepting a full JSON body, including GeoJSON geometries.
      tags:
      - Timelines
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimelinesRequest'
            examples:
              PostTimelinesRequestExample:
                summary: Default postTimelines request
                x-microcks-default: true
                value:
                  fields: &id009
                  - temperature
                  - humidity
                  - windSpeed
                  units: metric
                  timesteps: &id010
                  - 1h
                  startTime: now
                  endTime: nowPlus6h
                  timezone: America/New_York
                  dailyStartHour: 1
      responses:
        '200':
          description: Timeline response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimelinesResponse'
              examples:
                PostTimelines200Example:
                  summary: Default postTimelines 200 response
                  x-microcks-default: true
                  value:
                    data:
                      timelines:
                      - timestep: 1h
                        startTime: '2026-05-30T13:00:00Z'
                        endTime: '2026-05-30T13:00:00Z'
                        intervals:
                        - startTime: '2026-05-30T13:00:00Z'
                          values:
                            temperature: 21.2
                            temperatureApparent: 20.4
                            humidity: 64.0
                            dewPoint: 13.4
                            windSpeed: 3.1
                            windDirection: 220
                            windGust: 6.2
                            pressureSeaLevel: 1013.2
                            pressureSurfaceLevel: 1010.5
                            precipitationIntensity: 0.0
                            precipitationProbability: 5
                            precipitationType: 0
                            cloudCover: 12
                            cloudBase: 1.5
                            cloudCeiling: 2.4
                            visibility: 16
                            weatherCode: 1000
                            uvIndex: 6
                            uvHealthConcern: 2
                            epaIndex: 42
                            epaHealthConcern: 1
                            epaPrimaryPollutant: 0
                            particulateMatter25: 8.4
                            particulateMatter10: 14.1
                            pollutantO3: 28
                            pollutantNO2: 11
                            pollutantCO: 0.4
                            pollutantSO2: 1
                            treeIndex: 2
                            grassIndex: 1
                            weedIndex: 1
                            fireIndex: 8.2
                            solarGHI: 480
                            solarDIF: 120
                            solarDIR: 360
                            moonPhase: 3
                            hailBinary: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /historical:
    post:
      operationId: postHistoricalTimeline
      summary: Tomorrow.io Post Historical Timeline
      description: Returns historical weather timelines for a location, up to 20 years back.
      tags:
      - Historical
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HistoricalRequest'
            examples:
              PostHistoricalTimelineRequestExample:
                summary: Default postHistoricalTimeline request
                x-microcks-default: true
                value:
                  fields: &id011
                  - temperature
                  - precipitationIntensity
                  units: metric
                  timesteps: &id012
                  - 1d
                  startTime: '2024-01-01T00:00:00Z'
                  endTime: '2024-01-31T23:59:59Z'
                  timezone: example
      responses:
        '200':
          description: Historical timeline response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimelinesResponse'
              examples:
                PostHistoricalTimeline200Example:
                  summary: Default postHistoricalTimeline 200 response
                  x-microcks-default: true
                  value:
                    data:
                      timelines:
                      - timestep: 1h
                        startTime: '2026-05-30T13:00:00Z'
                        endTime: '2026-05-30T13:00:00Z'
                        intervals:
                        - startTime: '2026-05-30T13:00:00Z'
                          values:
                            temperature: 21.2
                            temperatureApparent: 20.4
                            humidity: 64.0
                            dewPoint: 13.4
                            windSpeed: 3.1
                            windDirection: 220
                            windGust: 6.2
                            pressureSeaLevel: 1013.2
                            pressureSurfaceLevel: 1010.5
                            precipitationIntensity: 0.0
                            precipitationProbability: 5
                            precipitationType: 0
                            cloudCover: 12
                            cloudBase: 1.5
                            cloudCeiling: 2.4
                            visibility: 16
                            weatherCode: 1000
                            uvIndex: 6
                            uvHealthConcern: 2
                            epaIndex: 42
                            epaHealthConcern: 1
                            epaPrimaryPollutant: 0
                            particulateMatter25: 8.4
                            particulateMatter10: 14.1
                            pollutantO3: 28
                            pollutantNO2: 11
                            pollutantCO: 0.4
                            pollutantSO2: 1
                            treeIndex: 2
                            grassIndex: 1
                            weedIndex: 1
                            fireIndex: 8.2
                            solarGHI: 480
                            solarDIF: 120
                            solarDIR: 360
                            moonPhase: 3
                            hailBinary: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /historical/normals:
    post:
      operationId: postClimateNormals
      summary: Tomorrow.io Post Climate Normals
      description: Returns 30-year monthly climate normals for a location.
      tags:
      - Climate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClimateNormalsRequest'
            examples:
              PostClimateNormalsRequestExample:
                summary: Default postClimateNormals request
                x-microcks-default: true
                value:
                  fields: &id013
                  - temperatureAvg
                  - precipitationAccumulationSum
                  units: metric
      responses:
        '200':
          description: Climate normals response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClimateNormalsResponse'
              examples:
                PostClimateNormals200Example:
                  summary: Default postClimateNormals 200 response
                  x-microcks-default: true
                  value:
                    data:
                      normals:
                      - month: 6
                        values:
                          temperature: 21.2
                          temperatureApparent: 20.4
                          humidity: 64.0
                          dewPoint: 13.4
                          windSpeed: 3.1
                          windDirection: 220
                          windGust: 6.2
                          pressureSeaLevel: 1013.2
                          pressureSurfaceLevel: 1010.5
                          precipitationIntensity: 0.0
                          precipitationProbability: 5
                          precipitationType: 0
                          cloudCover: 12
                          cloudBase: 1.5
                          cloudCeiling: 2.4
                          visibility: 16
                          weatherCode: 1000
                          uvIndex: 6
                          uvHealthConcern: 2
                          epaIndex: 42
                          epaHealthConcern: 1
                          epaPrimaryPollutant: 0
                          particulateMatter25: 8.4
                          particulateMatter10: 14.1
                          pollutantO3: 28
                          pollutantNO2: 11
                          pollutantCO: 0.4
                          pollutantSO2: 1
                          treeIndex: 2
                          grassIndex: 1
                          weedIndex: 1
                          fireIndex: 8.2
                          solarGHI: 480
                          solarDIF: 120
                          solarDIR: 360
                          moonPhase: 3
                          hailBinary: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /route:
    post:
      operationId: postRoute
      summary: Tomorrow.io Post Route
      description: Returns weather along the route for a polyline or list of waypoints with arrival-time interpolation.
      tags:
      - Routes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RouteRequest'
            examples:
              PostRouteRequestExample:
                summary: Default postRoute request
                x-microcks-default: true
                value:
                  route:
                    waypoints:
                    - location: &id001
                      - -71.0466
                      - 42.3478
                      arrivalTime: '2026-05-30T13:30:00Z'
                  fields: &id014
                  - temperature
                  - precipitationIntensity
                  - visibility
                  - windSpeed
                  units: metric
      responses:
        '200':
          description: Weather-on-route response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteResponse'
              examples:
                PostRoute200Example:
                  summary: Default postRoute 200 response
                  x-microcks-default: true
                  value:
                    data:
                      timelines:
                      - timestep: 1h
                        startTime: '2026-05-30T13:00:00Z'
                        endTime: '2026-05-30T13:00:00Z'
                        intervals:
                        - startTime: '2026-05-30T13:00:00Z'
                          values:
                            temperature: 21.2
                            temperatureApparent: 20.4
                            humidity: 64.0
                            dewPoint: 13.4
                            windSpeed: 3.1
                            windDirection: 220
                            windGust: 6.2
                            pressureSeaLevel: 1013.2
                            pressureSurfaceLevel: 1010.5
                            precipitationIntensity: 0.0
                            precipitationProbability: 5
                            precipitationType: 0
                            cloudCover: 12
                            cloudBase: 1.5
                            cloudCeiling: 2.4
                            visibility: 16
                            weatherCode: 1000
                            uvIndex: 6
                            uvHealthConcern: 2
                            epaIndex: 42
                            epaHealthConcern: 1
                            epaPrimaryPollutant: 0
                            particulateMatter25: 8.4
                            particulateMatter10: 14.1
                            pollutantO3: 28
                            pollutantNO2: 11
                            pollutantCO: 0.4
                            pollutantSO2: 1
                            treeIndex: 2
                            grassIndex: 1
                            weedIndex: 1
                            fireIndex: 8.2
                            solarGHI: 480
                            solarDIF: 120
                            solarDIR: 360
                            moonPhase: 3
                            hailBinary: 0
                      route:
                      - location: *id001
                        arrivalTime: '2026-05-30T13:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /map/tile/{zoom}/{x}/{y}/{field}/{timeFormat}:
    get:
      operationId: getMapTile
      summary: Tomorrow.io Get Map Tile
      description: Returns a raster tile for a weather field at a given time and zoom level.
      tags:
      - Map Tiles
      parameters:
      - name: zoom
        in: path
        required: true
        description: Web Mercator zoom level (typically 0-12).
        schema:
          type: integer
          minimum: 0
          maximum: 22
        example: 6
      - name: x
        in: path
        required: true
        description: Tile column.
        schema:
          type: integer
        example: 18
      - name: y
        in: path
        required: true
        description: Tile row.
        schema:
          type: integer
        example: 24
      - name: field
        in: path
        required: true
        description: Data field name to render (e.g. temperature, precipitationIntensity).
        schema:
          type: string
        example: temperature
      - name: timeFormat
        in: path
        required: true
        description: ISO 8601 time or relative offset.
        schema:
          type: string
        example: now
      responses:
        '200':
          description: PNG raster tile.
          content:
            image/png:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /locations:
    get:
      operationId: listLocations
      summary: Tomorrow.io List Locations
      description: Lists saved locations for the authenticated account.
      tags:
      - Locations
      responses:
        '200':
          description: Locations list.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Location'
              examples:
                ListLocations200Example:
                  summary: Default listLocations 200 response
                  x-microcks-default: true
                  value:
                  - id: 6183d156022c1b0008685cc6
                    name: Boston HQ Rooftop
                    geometry:
                      type: Point
                      coordinates: &id002
                      - -71.0466
                      - 42.3478
                    tags: &id003
                    - field-asset
                    - rooftop
                    createdAt: '2026-05-30T12:34:56Z'
                    updatedAt: '2026-05-30T12:34:56Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createLocation
      summary: Tomorrow.io Create Location
      description: Creates a new saved location (point, polygon, or polyline) with optional tags.
      tags:
      - Locations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationCreateRequest'
            examples:
              CreateLocationRequestExample:
                summary: Default 

# --- truncated at 32 KB (82 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tomorrow/refs/heads/main/openapi/tomorrow-openapi.yml