forge
Sign in Get your API key

Quickstart

Get your first weather response in under five minutes

Forge gives you global weather and geocoding data over a simple JSON REST API. This guide walks you through creating an account, generating an API key, and making your first request.

1. Create an account

Sign up at forge-api.dev/signup. No credit card is required to get started on the Free plan, which includes 60 requests per minute and 1,000 requests per day — plenty for local development.

2. Create an API key

Once you're signed in, open the dashboard and go to the API keys tab. Click Create key and give it a name (for example, local-dev).

The full key is shown once, immediately after creation. It looks like fg_live_xxxxxxxx. Copy it somewhere safe — Forge only ever stores a hash of it, so if you lose it you'll need to create a new one.

3. Make your first request

Every request must include your key in the Authorization header as a Bearer token. Here's a call to /v1/weather for London:

curl 'https://forge-api.dev/v1/weather?city=london' \
  -H 'Authorization: Bearer fg_live_xxxxxxxx'

Or with the JS SDK:

import Forge from '@forge-api/sdk';

const forge = new Forge('fg_live_xxxxxxxx');
const wx = await forge.weather({ city: 'london' });
console.log(wx.data.current.temp);

4. The response

A successful request returns a 200 with an ok envelope containing location, current conditions, and a multi-day forecast:

{
  "status": "ok",
  "data": {
    "location": {
      "name": "London",
      "region": "England",
      "country": "United Kingdom",
      "lat": 51.51,
      "lon": -0.13,
      "timezone": "Europe/London"
    },
    "current": {
      "temp": 18.2,
      "feels_like": 17.9,
      "temp_c": 18.2,
      "humidity": 72,
      "dew_point": 13.1,
      "wind_speed": 14.4,
      "wind_deg": 210,
      "wind_dir": "SSW",
      "pressure_mb": 1012,
      "visibility_km": 10,
      "cloud_cover": 40,
      "uv_index": 3,
      "precip_mm": 0,
      "condition": {
        "code": 1003,
        "text": "Partly cloudy",
        "icon": "partly-cloudy"
      },
      "observed_at": "2026-07-14T10:00:00Z"
    },
    "forecast": {
      "daily": [
        { "date": "2026-07-14", "temp_min": 13.5, "temp_max": 19.8, "condition": { "code": 1003, "text": "Partly cloudy", "icon": "partly-cloudy" } },
        { "date": "2026-07-15", "temp_min": 14.0, "temp_max": 21.2, "condition": { "code": 1000, "text": "Sunny", "icon": "sunny" } },
        { "date": "2026-07-16", "temp_min": 12.8, "temp_max": 18.1, "condition": { "code": 1180, "text": "Light rain", "icon": "light-rain" } }
      ]
    }
  },
  "meta": {
    "request_id": "req_8f2a1c4e9b3d",
    "credits_used": 1,
    "units": "metric",
    "generated_at": "2026-07-14T10:00:03Z"
  }
}

You can also look up weather by coordinates instead of a city name, and control units and forecast length:

curl 'https://forge-api.dev/v1/weather?lat=51.51&lon=-0.13&units=imperial&days=5' \
  -H 'Authorization: Bearer fg_live_xxxxxxxx'

Next steps