API Documentation

Welcome to the weatherstack API documentation. Using the instructions and interactive code examples below you will be able to start making API requests in a matter of minutes. If you have an account already and prefer to skip our detailed documentation, you can also jump to our 3-Step Quickstart Guide right away.

The weatherstack API was built to deliver accurate weather data for any application and use case, from real-time and historical weather information all the way to 14-day weather forecasts, supporting all major programming languages. Our straightforward API design will make it easy to use the API — continue reading below to get started.

Getting Started

API Authentication

The first step to using the API is to authenticate with your weatherstack account's unique API access key, which can be found in your account dashboard after registration. To authenticate with the API, simply use the base URL below and pass your API access key to the API's access_key parameter.

Example API Request:

Sign Up to Run API Requesthttps://api.weatherstack.com/current
    ? access_key = YOUR_ACCESS_KEY
    & query = New York

Keep it safe: Please make sure to keep your API access key and do not expose it in any publicly available part of your application. If you ever want to reset your key, simply head over to your account dashboard to do so.

256-bit HTTPS Encryption Available on: Standard Plan and higher

Clients using the Standard Plan or higher can connect to the weatherstack using industry-standard SSL (HTTPS) by attaching an s to the HTTP protocol as shown in the example API request below.

Example API Request:

https://api.weatherstack.com/...

If you are currently on the Free Plan and would like to use the HTTPS API in production, please upgrade your account now. You can also learn more about available plans on our Pricing Overview.

API Error Codes

Whenever an API request fails, the weatherstack API will return an error object in lightweight JSON format. Each error object contains an error code, an error type and an info object containing details about the error that occurred. Below you will find an example error as well as a list of common API errors.

Example API Error:

{
    "success": false,
    "error": {
        "code": 104,
        "type": "usage_limit_reached",
        "info": "Your monthly API request volume has been reached. Please upgrade your plan."    
    }
}                 

Common API Errors:

API Features

Current Weather Available on: All plans

To query the weatherstack API for real-time weather data in a location of your choice, simply attach your preferred location to the API's current endpoint as seen in the example request below. Depending on your subscription, you can also make a bulk location request by passing multiple semicolon-separated locations to the API URL.

Example API Request:

Sign Up to Run API Requesthttps://api.weatherstack.com/current
    ? access_key = YOUR_ACCESS_KEY
    & query = New York

HTTP GET Request Parameters:

Example API Response:

The successful API request from the example above now returns real-time weather data for the city of New York, including detailed information about temperature, humidity, wind, clouds, pressure, the current time, a series of location identifiers, and more.

{
    "request": {
        "type": "City",
        "query": "New York, United States of America",
        "language": "en",
        "unit": "m"
    },
    "location": {
        "name": "New York",
        "country": "United States of America",
        "region": "New York",
        "lat": "40.714",
        "lon": "-74.006",
        "timezone_id": "America/New_York",
        "localtime": "2019-09-07 08:14",
        "localtime_epoch": 1567844040,
        "utc_offset": "-4.0"
    },
    "current": {
        "observation_time": "12:14 PM",
        "temperature": 13,
        "weather_code": 113,
        "weather_icons": [
            "https://assets.weatherstack.com/images/wsymbols01_png_64/wsymbol_0001_sunny.png"
        ],
        "weather_descriptions": [
            "Sunny"
        ],
        "wind_speed": 0,
        "wind_degree": 349,
        "wind_dir": "N",
        "pressure": 1010,
        "precip": 0,
        "humidity": 90,
        "cloudcover": 0,
        "feelslike": 13,
        "uv_index": 4,
        "visibility": 16
    }
}

API Response Objects:

Historical Weather Available on: Standard Plan and higher

To look up historical weather data all the way back to 2008, simply pass one date of your choice (later than July 2008) or multiple semicolon-separated dates to the weatherstack API's historical endpoint using the historical_date parameter.

Example API Request:

Sign Up to Run API Requesthttps://api.weatherstack.com/historical
    ? access_key = YOUR_ACCESS_KEY
    & query = New York
    & historical_date = 2015-01-21
    & hourly = 1

HTTP GET Request Parameters:

Example API Response:

In addition to the requested historical weather data, a successful historical weather API call will also return the current weather in the location used for the request, as well as information about the API request and location.

{
    "request": {
        "type": "City",
        "query": "New York, United States of America",
        "language": "en",
        "unit": "m"
    },
    "location": {
        "name": "New York",
        "country": "United States of America",
        "region": "New York",
        "lat": "40.714",
        "lon": "-74.006",
        "timezone_id": "America/New_York",
        "localtime": "2019-09-07 10:05",
        "localtime_epoch": 1567850700,
        "utc_offset": "-4.0"
    },
    "current": {
        "observation_time": "02:05 PM",
        "temperature": 15,
        "weather_code": 113,
        "weather_icons": [
            "https://assets.weatherstack.com/images/wsymbols01_png_64/wsymbol_0001_sunny.png"
        ],
        "weather_descriptions": [
            "Sunny"
        ],
        "wind_speed": 0,
        "wind_degree": 0,
        "wind_dir": "N",
        "pressure": 1011,
        "precip": 0,
        "humidity": 78,
        "cloudcover": 0,
        "feelslike": 15,
        "uv_index": 5,
        "visibility": 16
    },
    "historical": {
        "2008-07-01": {
            "date": "2008-07-01",
            "date_epoch": 1214870400,
            "astro": {
                "sunrise": "05:29 AM",
                "sunset": "08:31 PM",
                "moonrise": "03:24 AM",
                "moonset": "07:37 PM",
                "moon_phase": "Waning Crescent",
                "moon_illumination": 4
            },
            "mintemp": 0,
            "maxtemp": 0,
            "avgtemp": 19,
            "totalsnow": 0,
            "sunhour": 14.5,
            "uv_index": 4,
            "hourly": [
                {
                    "time": "0",
                    "temperature": 27,
                    "wind_speed": 7,
                    "wind_degree": 201,
                    "wind_dir": "SSW",
                    "weather_code": 113,
                    "weather_icons": [
                        "https://assets.weatherstack.com/images/wsymbols01_png_64/wsymbol_0001_sunny.png"
                    ],
                    "weather_descriptions": [
                        "Sunny"
                    ],
                    "precip": 1.8,
                    "humidity": 80,
                    "visibility": 9,
                    "pressure": 1011,
                    "cloudcover": 15,
                    "heatindex": 25,
                    "dewpoint": 20,
                    "windchill": 24,
                    "windgust": 11,
                    "feelslike": 25,
                    "chanceofrain": 0,
                    "chanceofremdry": 0,
                    "chanceofwindy": 0,
                    "chanceofovercast": 0,
                    "chanceofsunshine": 0,
                    "chanceoffrost": 0,
                    "chanceofhightemp": 0,
                    "chanceoffog": 0,
                    "chanceofsnow": 0,
                    "chanceofthunder": 0,
                    "uv_index": 6
                },
                {   "time": "300", ...   },
                {   "time": "600", ...   },
                // 6 more items
            ]
        }
    }
}

Please note: The response objects request, location and current will not be explained below as they are already mentioned in the Current Weather Endpoint section above.

API Response Objects:

Historical Time-Series Available on: Standard Plan and higher

In addition to looking up historical weather data for specific dates, the API is also capable of processing historical time-series results if the parameters historical_date_start and historical_date_end are set to valid dates.

Example API Request:

Sign Up to Run API Requesthttps://api.weatherstack.com/historical
    ? access_key = YOUR_ACCESS_KEY
    & query = New York
    & historical_date_start = 2015-01-21
    & historical_date_end = 2015-01-25

HTTP GET Request Parameters:

API Response:

For more information about the API response, please refer to the API response in the Historical Weather section above.

Please note: The historical time-series can accept a maximum timeframe of 60 days.

Note: Each day and location included in your request will count towards your monthly allowed API request volume.

Weather Forecast Available on: Professional Plan and higher

The weatherstack is capable of returning weather forecast data for up to 14 days into the future. To get weather forecasts, simply use the API's forecast and define your preferred number of forecast days using the forecast_days parameter.

Example API Request:

Sign Up to Run API Requesthttps://api.weatherstack.com/forecast
    ? access_key = YOUR_ACCESS_KEY
    & query = New York
    & forecast_days = 1
    & hourly = 1

HTTP GET Request Parameters:

Note: Each day and location included in your request will count towards your monthly allowed API request volume.

API Response:

{
    "request": {
        "type": "City",
        "query": "New York, United States of America",
        "language": "en",
        "unit": "m"
    },
    "location": {
        "name": "New York",
        "country": "United States of America",
        "region": "New York",
        "lat": "40.714",
        "lon": "-74.006",
        "timezone_id": "America/New_York",
        "localtime": "2019-09-07 11:38",
        "localtime_epoch": 1567856280,
        "utc_offset": "-4.0"
    },
    "current": {
        "observation_time": "03:38 PM",
        "temperature": 18,
        "weather_code": 113,
        "weather_icons": [
            "https://assets.weatherstack.com/images/wsymbols01_png_64/wsymbol_0001_sunny.png"
        ],
        "weather_descriptions": [
            "Sunny"
        ],
        "wind_speed": 0,
        "wind_degree": 345,
        "wind_dir": "NNW",
        "pressure": 1011,
        "precip": 0,
        "humidity": 58,
        "cloudcover": 0,
        "feelslike": 18,
        "uv_index": 5,
        "visibility": 16
    },
    "forecast": {
        "2019-09-07": {
            "date": "2019-09-07",
            "date_epoch": 1567814400,
            "astro": {
                "sunrise": "06:28 AM",
                "sunset": "07:19 PM",
                "moonrise": "03:33 PM",
                "moonset": "12:17 AM",
                "moon_phase": "First Quarter",
                "moon_illumination": 54
            },
            "mintemp": 17,
            "maxtemp": 25,
            "avgtemp": 21,
            "totalsnow": 0,
            "sunhour": 10.3,
            "uv_index": 5,
            "hourly": [
                {
                    "time": "0",
                    "temperature": 18,
                    "wind_speed": 28,
                    "wind_degree": 15,
                    "wind_dir": "NNE",
                    "weather_code": 122,
                    "weather_icons": [
                        "https://assets.weatherstack.com/images/wsymbols01_png_64/wsymbol_0004_black_low_cloud.png"
                    ],
                    "weather_descriptions": [
                        "Overcast"
                    ],
                    "precip": 0,
                    "humidity": 68,
                    "visibility": 10,
                    "pressure": 1008,
                    "cloudcover": 75,
                    "heatindex": 18,
                    "dewpoint": 12,
                    "windchill": 18,
                    "windgust": 35,
                    "feelslike": 18,
                    "chanceofrain": 0,
                    "chanceofremdry": 87,
                    "chanceofwindy": 0,
                    "chanceofovercast": 90,
                    "chanceofsunshine": 15,
                    "chanceoffrost": 0,
                    "chanceofhightemp": 0,
                    "chanceoffog": 0,
                    "chanceofsnow": 0,
                    "chanceofthunder": 0,
                    "uv_index": 0
                },
                {   "time": "300", ...   },
                {   "time": "600", ...   },
                // 6 more items
            ]
        }
    }
}

Please note: The response objects request, location and current will not be explained below as they are already mentioned in the Current Weather Endpoint section.

API Response Objects:

Location Lookup/Autocomplete Available on: Standard Plan and higher

The weatherstack API's location autocomplete endpoint can be used to pinpoint one or more specific locations and their identifying response objects with the aim of later passing them to a weather data endpoint. In our example below, we are looking for London, United Kingdom.

Example API Request:

Sign Up to Run API Requesthttps://api.weatherstack.com/autocomplete
    ? access_key = YOUR_ACCESS_KEY
    & query = london

HTTP GET Request Parameters:

API Response:

A successful API request will return one or multiple results that match your search query. In our example, the first array object (London, United Kingdom) contains the correct result. Now that we have our identifying response objects of the target location we were looking for, we can make sure that the correct location is used by other API endpoints by using one of the available location identifiers (ideally: lat and lon) for upcoming queries.

{
    "request": {
        "query": "london",
        "results": 2
    },
    "results": [
        {
            "name": "London",
            "country": "United Kingdom",
            "region": "City of London, Greater London",
            "lon": "-0.106",
            "lat": "51.517",
            "timezone_id": "Europe/London",
            "utc_offset": "1.0"
        },
        {
            "name": "London",
            "country": "Canada",
            "region": "Ontario",
            "lon": "-81.250",
            "lat": "42.983",
            "timezone_id": "America/Toronto",
            "utc_offset": "-4.0"
        }
    ]
}    

API Response Objects:

General Options

Query Parameter Available on: All plans

The API's query parameter can be used in various ways to pass a single location or multiple locations to the API when making requests to one of the API's weather data endpoints. Using the example of the API's current endpoint, all available options will be outlined below:

Single Location:

The most common use case for the query parameter is to pass a single location to the API when making a weather data request. Find an example below:

Sign Up to Run API Requesthttps://api.weatherstack.com/current
    ? access_key = YOUR_ACCESS_KEY
    & query = London, United Kingdom

Multiple Locations: (Professional Plan and higher)

To make use of the API's bulk query capability, you can also pass multiple semicolon-separated locations to the API:

Sign Up to Run API Requesthttps://api.weatherstack.com/current
    ? access_key = YOUR_ACCESS_KEY
    & query = London;Singapur;Shanghai

Supported Location Identifiers:

Aside from simply passing the name of a city, there are multiple other ways of passing a location to the API:

Note: Each location passed to this parameter as part of a bulk query will count towards your monthly request volume.

Units Parameter Available on: All plans

By default, the API will return all results in metric units. Aside from metric units, other common unit formats are supported as well. You can use the units parameter to switch between the different unit formats Metric, Scientific and Fahrenheit.

m for Metric:

s for Scientific:

f for Fahrenheit:

Language Parameter Available on: Professional Plan and higher

The API is capable of delivering results in a total of 40 world languages. To change the default value (English) to another language, simply attach the language parameter to your API URL and set it to the 2-letter ISO Code of your preferred language.

Supported Languages:

JSONP Callbacks Available on: All plans

The API supports JSONP Callbacks. To make use of this feature, simply append the API's callback parameter to your API request URL and set it to your preferred function name. The API will then return your API results set wrapped inside the tags of the function you specified.

Example API Request:

Sign Up to Run API Requesthttps://api.weatherstack.com/current
    ? access_key = YOUR_ACCESS_KEY
    & query = New York
    & callback = FUNCTION_NAME

Example API Response:

CALLBACK_FUNCTION ({
    {
    "request": {
        "type": "City",
        "query": "New York, United States of America",
        "language": "en",
        [...]
    }
})             

Please note: The API also supports Access-Control (CORS) headers.

Code Examples

Find below a series of straightforward code examples in different programming languages, all requesting and printing the latest available weather.

Code Example - PHP

$location = 'New York';

$queryString = http_build_query([
  'access_key' => 'YOUR_ACCESS_KEY',
  'query' => $location,
]);

$ch = curl_init(sprintf('%s?%s', 'https://api.weatherstack.com/current', $queryString));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$json = curl_exec($ch);
curl_close($ch);

$api_result = json_decode($json, true);

echo "Current temperature in $location is {$api_result['current']['temperature']}℃", PHP_EOL;

Code Example - Python

# coding: utf-8
import requests

params = {
  'access_key': 'YOUR_ACCESS_KEY',
  'query': 'New York'
}

api_result = requests.get('https://api.weatherstack.com/current', params)

api_response = api_result.json()

print(u'Current temperature in %s is %d℃' % (api_response['location']['name'], api_response['current']['temperature']))

Code Example - Nodejs

const axios = require('axios');
const params = {
  access_key: 'YOUR_ACCESS_KEY',
  query: 'New York'
}

axios.get('https://api.weatherstack.com/current', {params})
  .then(response => {
    const apiResponse = response.data;
    console.log(`Current temperature in ${apiResponse.location.name} is ${apiResponse.current.temperature}℃`);
  }).catch(error => {
    console.log(error);
  });

Code Example - jQuery

$.ajax({
  url: 'https://api.weatherstack.com/current',
  data: {
    access_key: 'YOUR_ACCESS_KEY',
    query: 'New York'
  },
  dataType: 'json',
  success: function(apiResponse) {
    console.log(`Current temperature in ${apiResponse.location.name} is ${apiResponse.current.temperature}℃`);
  }
});

Code Example - Go

package main

import (
  "encoding/json"
  "fmt"
  "net/http"
)

type Location struct {
  Name string `json:"name"`
}

type Weather struct {
  Temperature int `json:"temperature"`
}

type Response struct {
	Location Location `json:"location"`
	Current Weather `json:"current"`
}

func main() {
  httpClient := http.Client{}

  req, err := http.NewRequest("GET", "https://api.weatherstack.com/current", nil)
  if err != nil {
    panic(err)
  }

  q := req.URL.Query()
  q.Add("access_key", "YOUR_ACCESS_KEY")
  q.Add("query", "New York")
  req.URL.RawQuery = q.Encode()

  res, err := httpClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer res.Body.Close()

  var apiResponse Response
  json.NewDecoder(res.Body).Decode(&apiResponse)

  fmt.Println(fmt.Sprintf("Current temperature in %s is %d℃", apiResponse.Location.Name, apiResponse.Current.Temperature))
}

Code Example - Ruby

require 'net/http'
require 'json'

params = {
  :access_key => "YOUR_ACCESS_KEY",
  :query => "New York"
}
uri = URI('https://api.weatherstack.com/current')
uri.query = URI.encode_www_form(params)
json = Net::HTTP.get(uri)
api_response = JSON.parse(json)

puts "Current temperature in #{api_response['location']['name']} is #{api_response['current']['temperature']}"

Business Continuity - API Overages

Ensuring our customers achieve success is paramount to what we do at APILayer. For this reason, we will be rolling out our Business Continuity plan guaranteeing your end users will never see a drop in coverage. Every plan has a certain amount of API calls that you can make in the given month. However, we would never want to cut your traffic or impact user experience negatively for your website or application in case you get more traffic.

What is an overage?

An overage occurs when you go over a quota for your API plan. When you reach your API calls limit, we will charge you a small amount for each new API call so we can make sure there will be no disruption in the service we provide to you and your website or application can continue running smoothly.

Prices for additional API calls will vary based on your plan. See table below for prices per call and example of an overage billing.

Why does APILayer have overage fees?

Overage fees allow developers to continue using an API once a quota limit is reached and give them time to upgrade their plan based on projected future use while ensuring API providers get paid for higher usage.

How do I know if I will be charged for overages?

When you are close to reaching your API calls limit for the month, you will receive an automatic notification (at 75%, 90% and 100% of your monthly quota). However, it is your responsibility to review and monitor for the plan’s usage limitations. You are required to keep track of your quota usage to prevent overages. You can do this by tracking the number of API calls you make and checking the dashboard for up-to-date usage statistics.

How will I be charged for my API subscription?

You will be charged for your monthly subscription plan, plus any overage fees applied. Your credit card will be billed after the billing period has ended.

What happens if I don’t have any overage fees?

In this case, there will be no change to your monthly invoice. Only billing cycles that incur overages will see any difference in monthly charges. The Business Continuity plan is an insurance plan to be used only if needed and guarantees your end users never see a drop in coverage from you.

What if I consistently have more API calls than my plan allows?

If your site consistently surpasses the set limits each month, you may face additional charges for the excess usage. Nevertheless, as your monthly usage reaches a certain threshold, it becomes more practical to consider upgrading to the next plan. By doing so, you ensure a smoother and more accommodating experience for your growing customer base.

I would like to upgrade my plan. How can I do that?

You can easily upgrade your plan by going to your Dashboard and selecting the new plan that would be more suitable for your business needs. Additionally, you may contact your Account Manager to discuss a custom plan if you expect a continuous increase in usage.

Introducing Platinum Support - Enterprise-grade support for APILayer

Upgrade your APIlayer subscription with our exclusive Platinum Support, an exceptional offering designed to enhance your business’ API management journey. With Platinum Support, you gain access to a host of premium features that take your support experience to a whole new level.

What does Platinum Support include?

	Standard Support	Platinum Support
General review on the issue
Access to knowledge base articles
Email support communication
Regular products updates and fixes
Dedicated account team
Priority Email Support with unlimited communication
Priority bug and review updates
Option for quarterly briefing call with product Management
Features requests as priority roadmap input into product

Priority Email Support: Experience unrivaled responsiveness with our priority email support. Rest assured that your inquiries receive top-priority attention, ensuring swift resolutions to any issues.

Unlimited Communication: Communication is key, and with Platinum Support, you enjoy unlimited access to our support team. No matter how complex your challenges are, our experts are here to assist you every step of the way.

Priority Bug Review and Fixes: Bugs can be a headache, but not with Platinum Support. Benefit from accelerated bug review and fixes, minimizing disruptions and maximizing your API performance.

Dedicated Account Team: We understand the value of personalized attention. That's why Platinum Support grants you a dedicated account team, ready to cater to your specific needs and provide tailored solutions.

Quarterly Briefing Call with Product Team: Stay in the loop with the latest updates and insights from our Product team. Engage in a quarterly briefing call to discuss new features, enhancements, and upcoming developments.

Priority Roadmap Input: Your input matters! As a Platinum Support subscriber, your feature requests receive top priority, shaping our product roadmap to align with your evolving requirements.

Don't settle for the standard when you can experience the exceptional. Upgrade to Platinum Support today and supercharge your APIlayer experience!