Foreca Weather API · Documentation

Python Weather API Quickstart

Fetch current weather, an hourly and a daily forecast for any place with Python and the requests library.

Get an API key

Before you start

You need Python 3.8 or later, the requests library and an API key. The Quickstart shows how to get a key.

Terminal
python3 -m pip install requests
export FORECA_API_KEY="paste-your-key-here"

In Windows PowerShell, set the key with $env:FORECA_API_KEY = "paste-your-key-here".

Current weather

The smallest useful request: the weather now at a coordinate, longitude first.

current.py
import os
import requests

API = "https://weatherapi.foreca.net"
headers = {"Authorization": f"Bearer {os.environ['FORECA_API_KEY']}"}

r = requests.get(f"{API}/api/v1/current/24.94,60.17", headers=headers, timeout=10)
r.raise_for_status()
current = r.json()["current"]
print(current["time"], current["temperature"], "°C,", current["symbolPhrase"])

Run it with python3 current.py. raise_for_status() turns an error status into an exception, so a wrong key fails loudly instead of printing nothing.

Hourly and daily forecast for any place

This script finds a place by name, then prints the weather now, the next 12 hours and the next 7 days. One Session sends the key with every request and reuses the connection.

weather.py
import os
import sys
import requests

API = "https://weatherapi.foreca.net"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['FORECA_API_KEY']}"


def get(path, **params):
    r = session.get(f"{API}{path}", params=params, timeout=10)
    if not r.ok:
        sys.exit(f"{r.status_code}: {r.text}")
    return r.json()


place = sys.argv[1] if len(sys.argv) > 1 else "Helsinki"
locations = get(f"/api/v1/location/search/{place}")["locations"]
if not locations:
    sys.exit(f"No location called {place}")
location = locations[0]
print(f"{location['name']}, {location['country']}")

current = get(f"/api/v1/current/{location['id']}")["current"]
print(f"Now: {current['temperature']} °C, {current['symbolPhrase']}")

print("Next 12 hours:")
for hour in get(f"/api/v1/forecast/hourly/{location['id']}", periods=12)["forecast"]:
    print(f"  {hour['time'][11:16]}  {hour['temperature']:>3} °C  wind {hour['windSpeed']} m/s  {hour['precipProb']} %")

print("Next 7 days:")
for day in get(f"/api/v1/forecast/daily/{location['id']}", periods=7)["forecast"]:
    print(f"  {day['date']}  {day['minTemp']}…{day['maxTemp']} °C  {day['precipAccum']} mm")

Run it with a place name: python3 weather.py London. Hourly time is the location's local time, and precipProb the chance of precipitation in percent.

Errors

On an error status, get() stops the script and prints the status and the API's JSON body, for example 401: {"error":"invalid_token",…}. When a request fails lists what each error means. On 429, wait the number of seconds in the Retry-After header before you retry.

Next steps