Tomorrow.io Logo

Quick Start Guide

This guide will help you make your first API request and understand the basic concepts of the Tomorrow.io Weather API. You'll be getting weather data in just a few minutes!

Prerequisites

API Key Required

You'll need a Tomorrow.io API key to make requests. The API key authenticates your requests and tracks your usage.

Information

Don't have an API key yet? Sign up for free to get started with 1,000 API calls per day.

Free Tier Includes:

  • • 1,000 API calls per day
  • • Hourly and daily forecasts
  • • Real-time weather data
  • • Historical weather data
  • • Core weather data fields

Basic Knowledge

This guide assumes basic familiarity with:

  • • HTTP requests - Understanding GET requests and URL parameters
  • • JSON format - Ability to read and parse JSON responses
  • • Command line or Programming basics - For making API calls

Your First Request

Let's start with the most common use case: getting the current weather forecast for a location. We'll use the Weather Forecast API to get hourly forecasts for New York.

Using cURL (Command Line)

cURL RequestBASH
curl -X GET "https://api.tomorrow.io/v4/weather/forecast?location=new%20york&timesteps=1h&apikey=YOUR_API_KEY"

Breaking Down the Request:

  • Base URL: https://api.tomorrow.io/v4/weather/forecast
  • location: new%20york - The location you want weather for
  • timesteps: 1h - Hourly forecast intervals
  • apikey: YOUR_API_KEY - Replace with your actual API key

Information

Important: Replace YOUR_API_KEY with your actual API key from your Tomorrow.io dashboard.

Understanding the Response

The API returns a JSON response with weather data organized in a specific structure. Here's what you'll get back:

JSON ResponseJSON
{
  "data": {
    "timelines": [
      {
        "timestep": "1h",
        "endTime": "2025-01-15T12:00:00Z",
        "startTime": "2025-01-15T06:00:00Z",
        "intervals": [
          {
            "startTime": "2025-01-15T06:00:00Z",
            "values": {
              "temperature": 15.5,
              "temperatureApparent": 13.2,
              "humidity": 65,
              "windSpeed": 3.2,
              "windDirection": 225,
              "precipitationIntensity": 0,
              "precipitationProbability": 10,
              "weatherCode": 1000,
              "uvIndex": 2
            }
          }
        ]
      }
    ]
  },
  "location": {
    "lat": 40.7589,
    "lon": -73.9851,
    "name": "New York, NY, USA",
    "type": "administrative"
  }
}

Response Breakdown

Weather Data

  • • temperature: Current temperature (°C)
  • • temperatureApparent: "Feels like" temperature
  • • humidity: Relative humidity (%)
  • • windSpeed: Wind speed (m/s)
  • • weatherCode: Condition identifier

Location Info

  • • lat/lon: Precise coordinates
  • • name: Resolved location name
  • • type: Location type classification

Code Examples

JavaScript / Node.js

JavaScriptJAVASCRIPT
// Using fetch API
async function getWeatherForecast(location, apiKey) {
  const url = `https://api.tomorrow.io/v4/weather/forecast?location=${encodeURIComponent(location)}&timesteps=1h&apikey=${apiKey}`;
  
  try {
    const response = await fetch(url);
    
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    
    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Error fetching weather data:', error);
    throw error;
  }
}

// Usage
getWeatherForecast('New York', 'YOUR_API_KEY')
  .then(data => {
    console.log('Current temperature:', data.data.timelines[0].intervals[0].values.temperature);
  })
  .catch(error => {
    console.error('Failed to get weather:', error);
  });

Python

PythonPYTHON
import requests
import json

def get_weather_forecast(location, api_key):
    """
    Get weather forecast for a location using Tomorrow.io API
    """
    url = "https://api.tomorrow.io/v4/weather/forecast"
    
    params = {
        'location': location,
        'timesteps': '1h',
        'apikey': api_key
    }
    
    try:
        response = requests.get(url, params=params)
        response.raise_for_status()  # Raises an HTTPError for bad responses
        
        return response.json()
    
    except requests.exceptions.RequestException as e:
        print(f"Error fetching weather data: {e}")
        raise

# Usage
if __name__ == "__main__":
    API_KEY = "YOUR_API_KEY"
    location = "New York"
    
    try:
        weather_data = get_weather_forecast(location, API_KEY)
        current_temp = weather_data['data']['timelines'][0]['intervals'][0]['values']['temperature']
        print(f"Current temperature in {location}: {current_temp}°C")
    except Exception as e:
        print(f"Failed to get weather: {e}")

Next Steps

Explore More APIs

Now that you've made your first request, explore other weather APIs:

Learn Best Practices

Optimize your integration with our guides:

Common Issues

Authentication Errors

If you get a 401 Unauthorized error, check that:

  • • Your API key is correct and active
  • • You haven't exceeded your daily quota
  • • The API key is properly URL-encoded in the request

Location Not Found

If you get a location error, try:

  • • Using coordinates instead of city names: 40.7589,-73.9851
  • • Being more specific: "New York, NY, USA" instead of "New York"
  • • Using postal codes: "10001 US"