Introducing the Forge v1 API

Today we're shipping Forge v1, the next evolution of our weather and geocoding API. Over the past six months, we've listened to thousands of developers and hundreds of production deployments. The result is an API that's cleaner to use, faster to integrate with, and built to scale with your ambitions.

This is a significant milestone for Forge. We're moving beyond v0 as a proof of concept and into v1 as a platform.

Structured Responses with Envelope Design

The most visible change in v1 is our new response envelope. Every response, whether successful or not, now follows a consistent structure:

{
  "status": "ok",
  "data": {
    "temperature": 15.2,
    "humidity": 72
  },
  "meta": {
    "request_id": "req_xyz789",
    "credits_used": 1,
    "generated_at": "2024-06-12T14:23:11Z"
  }
}

This structure was inspired by conversations with teams building on Forge. Most API clients need to know: did this work? How much did it cost? Can I reproduce this request if needed? Our envelope answers all three.

Bearer Token Authentication

v0 used query parameter authentication, which was simple but problematic for real production systems. Your API key was visible in logs, browser history, and cache headers. v1 moves to standard HTTP Bearer authentication:

curl -H "Authorization: Bearer fg_live_abc123def456" \
  https://forge-api.dev/v1/weather?lat=51.51&lon=-0.13&units=metric

This change aligns with industry best practices and makes it significantly easier to rotate compromised keys or scope them to specific environments. We provide full tooling in the dashboard for managing your tokens.

Consistent Error Handling

Errors in v1 also use the envelope structure, with standardized error codes and a link to our error documentation:

{
  "status": "error",
  "error": {
    "code": "missing_api_key",
    "message": "Authorization header is required",
    "doc_url": "https://forge-api.dev/docs/errors"
  }
}

This consistency means your client code can handle errors more gracefully, and you spend less time debugging.

Coordinates Instead of City Names

v0 took city names directly: ?city=london. Ambiguous (which London?), and inflexible. v1 uses latitude and longitude:

curl -H "Authorization: Bearer fg_live_..." \
  https://forge-api.dev/v1/weather?lat=51.51&lon=-0.13&units=metric

If you have a city name, use our dedicated geocoding endpoint first:

curl -H "Authorization: Bearer fg_live_..." \
  https://forge-api.dev/v1/geocode?q=london&limit=5

This separation of concerns makes both endpoints simpler and more predictable.

Flexible Time Horizons

By default, we return 3 days of forecast. You can request 1 to 7 days:

curl -H "Authorization: Bearer fg_live_..." \
  https://forge-api.dev/v1/weather?lat=51.51&lon=-0.13&days=7

Longer forecasts have lower accuracy, but sometimes you need the look-ahead.

Unit Support

Metric by default, but we support imperial:

curl -H "Authorization: Bearer fg_live_..." \
  https://forge-api.dev/v1/weather?lat=40.71&lon=-74.01&units=imperial

Temperature in Fahrenheit, wind in mph, distance in miles.

Migrating from v0

We know that v0 has users in production. We're committing to keep v0 available until December 31, 2026. That gives everyone plenty of time to migrate. The changes are straightforward:

Replace query-param auth with Bearer tokens
Update your response parsing to handle the new envelope
Swap v0 for v1 in your API paths
Use coordinates instead of city names

We've published a detailed migration guide with code examples for all popular languages.

What's Next

v1 is just the beginning. In the coming months, we're planning official SDKs for JavaScript, Python, and Go. We're adding historical weather data archives. We're building a GraphQL API for power users. We're excited about the possibilities.

Get Started

Head to forge-api.dev. Sign up for free and make your first request in under two minutes. We can't wait to see what you build.