Weather API Quickstart: Your First Request

Get a key, find a location and fetch an hourly forecast. The examples use curl; the Python and JavaScript quickstarts do the same in code.

Get an API key

Sign up and choose a plan on the pricing page: the 30-day free trial, the free Freemium plan for non-commercial use, or a paid plan. Then open My API, select Add new key and copy the key. Keys do not expire, and you can delete one on the same page.

Keep the key out of your code and pass it in an environment variable. In a terminal on macOS or Linux:

Terminal

export FORECA_API_KEY="paste-your-key-here"

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

Find a location

Forecasts are asked for a location. Search for one by name:

Terminal

curl -H "Authorization: Bearer $FORECA_API_KEY" \
  "https://weatherapi.foreca.net/api/v1/location/search/Helsinki"

Each match has an id. The first two matches:

Response

{
  "locations": [
    {
      "id": 100658225,
      "name": "Helsinki",
      "country": "Finland",
      "timezone": "Europe/Helsinki",
      "language": "en",
      "adminArea": "Uusimaa",
      "adminArea2": "Helsinki",
      "adminArea3": "Helsinki",
      "lon": 24.9354,
      "lat": 60.1695
    },
    {
      "id": 220000024,
      "name": "Helsinki Golf Club",
      "country": "Finland",
      "timezone": "Europe/Helsinki",
      "language": "en",
      "adminArea": null,
      "adminArea2": null,
      "adminArea3": null,
      "lon": 24.8638,
      "lat": 60.2118
    }
  ]
}

You can also skip the search and give coordinates, longitude first: 24.94,60.17.

Fetch an hourly forecast

Ask for the next three hours at the location id:

Terminal

curl -H "Authorization: Bearer $FORECA_API_KEY" \
  "https://weatherapi.foreca.net/api/v1/forecast/hourly/100658225?periods=3"

Response

{
  "forecast": [
    {
      "time": "2026-10-19T15:00+03:00",
      "symbol": "d300",
      "temperature": 9,
      "feelsLikeTemp": 8,
      "windSpeed": 2,
      "windGust": 4,
      "windDir": 188,
      "windDirString": "S",
      "precipProb": 1,
      "precipAccum": 0
    },
    {
      "time": "2026-10-19T16:00+03:00",
      "symbol": "d200",
      "temperature": 9,
      "feelsLikeTemp": 9,
      "windSpeed": 2,
      "windGust": 3,
      "windDir": 168,
      "windDirString": "S",
      "precipProb": 1,
      "precipAccum": 0
    },
    {
      "time": "2026-10-19T17:00+03:00",
      "symbol": "d100",
      "temperature": 9,
      "feelsLikeTemp": 8,
      "windSpeed": 2,
      "windGust": 3,
      "windDir": 145,
      "windDirString": "SE",
      "precipProb": 1,
      "precipAccum": 0
    }
  ]
}

Read the response

time: the hour, in the location's local time with its UTC offset.
symbol: the weather as a code. Weather icons and symbol codes lists what each one means.
temperature and feelsLikeTemp: degrees Celsius.
windSpeed and windGust: metres per second. windDir: wind direction in degrees, and windDirString the same as a compass point.
precipProb: the probability of precipitation in the hour up to time, in percent. precipAccum: precipitation in that hour, in millimetres.

Add dataset=full for humidity, pressure, cloudiness, UV index and more.

Change units and length

Query parameters shape the response:

Parameter	Values
`periods`	Number of hours, 24 by default and up to 169.
`tempunit`	`C` (default) or `F`.
`windunit`	`MS` (default), `KMH`, `MPH` or `KTS`.
`tz`	A time zone name such as `Europe/London`. By default, the location's own.
`lang`	Language of text fields, such as `de` or `fr`.

Terminal

curl -H "Authorization: Bearer $FORECA_API_KEY" \
  "https://weatherapi.foreca.net/api/v1/forecast/hourly/100658225?periods=12&tempunit=F&windunit=MPH"

The Hourly reference lists every parameter.

When a request fails

A failed request answers with an HTTP error status and a JSON body that says what went wrong:

Response

{
  "error": "no_token",
  "message": "No token provided. Pass the JWT in the Authorization header (Bearer …) or as a `token` query parameter."
}

Status	`error`	What it means
401	`no_token`	The request has no key. Send it as `Authorization: Bearer <key>`.
401	`invalid_token`	The key is wrong, incomplete or expired. Copy it again.
401	`wrong_endpoint`	The key belongs to the other API host. The `endpoint` field in the response names the right one.
401	`account_inactive`	The account or its plan is no longer active.
403	`product_unavailable`	Your plan does not include this feature. See the plans.
403	`trial_restriction`	The free trial covers this data only for a limited area or period. The message says which.
429	`rate_limited`	Too many requests per second. Wait the number of seconds in the `Retry-After` header, then retry.
429	`daily_quota_exceeded`	The free trial or Freemium plan has used its 2,000 requests for the day. The count resets at 00:00 UTC.
429	`quota_exceeded`	The plan has used its requests for the month. The count resets with the next billing period.

Only successful requests count towards your plan's limits.

Next steps

Python quickstart: the same requests in a Python script.
JavaScript quickstart: Node.js, and a web page that keeps your key on a server.
Point Forecasts reference: every parameter and response field of the current, hourly and daily forecasts.
Weather icons and symbol codes: what each symbol code means, and icon sets to download.
Usage endpoint: how many requests your key has used.