Name: Weather API - Real-Time Forecasts, Air Quality & Geocoding
Brand: quotalink
SKU: api-quotalink-weather-api
Availability: InStock
Author: API Market

李乐

## Overview

Weather API gives you current conditions, daily and hourly forecasts, air quality and place-name geocoding for anywhere in the world, from a single base URL. Responses are flat, predictable JSON with weather codes already translated into readable descriptions, so you can render a forecast without shipping your own lookup table.

Coordinates drive every weather endpoint. If you only have a place name, call `/geocode` first to turn it into latitude and longitude.

## Features

- **Current conditions**: temperature, apparent temperature, humidity, wind speed and direction, updated on a 15 minute interval.
- **7 day forecast**: daily minimum and maximum temperature, precipitation totals and probability, and maximum wind speed.
- **24 hour outlook**: hourly temperature, precipitation probability, wind speed and weather codes.
- **Air quality**: PM2.5, PM10, ozone, nitrogen dioxide, sulphur dioxide, carbon monoxide plus European and US AQI.
- **Built-in geocoding**: resolve a place name to coordinates without leaving the API.
- **Readable weather codes**: every `weather_code` ships alongside a `weather_description` such as `Mainly clear`.
- **No provider account needed**: your API.market key is the only credential.

## Use Cases

- **Consumer weather apps**: current conditions and a 7 day strip from two calls.
- **Logistics and field operations**: plan routes and crews around precipitation probability and wind.
- **Agriculture and irrigation**: daily precipitation sums to drive watering schedules.
- **Health and air quality alerts**: notify users when AQI crosses a threshold.
- **Travel and events**: show destination weather at booking time.
- **Energy forecasting**: hourly temperature and wind as demand and generation inputs.

## API Documentation

### Base URL

```
https://prod.api.market/api/v1/quotalink/weather-api
```

### Authentication

Pass your API.market key in the `x-api-market-key` header on every request. No other credential is needed.

```
x-api-market-key: YOUR_API_MARKET_KEY
```

Find your key under **Account → API Keys** on api.market. Requests without this header return `400` with `No x-api-market-key or x-magicapi-key defined in headers`.

### Coordinates

The four weather endpoints require `latitude` and `longitude` as query parameters. Spell them out in full, because abbreviations such as `lat` and `lon` are not accepted and return a `400`.

| Parameter | Range | Example |
| --- | --- | --- |
| `latitude` | -90 to 90 | `51.5074` |
| `longitude` | -180 to 180 | `-0.1278` |

The `location` object echoed in each response contains the coordinates of the nearest grid cell actually used, which will differ slightly from what you sent.

### Endpoints

#### GET /current

Current conditions for a coordinate pair.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `latitude` | query | number | Yes | Latitude in decimal degrees |
| `longitude` | query | number | Yes | Longitude in decimal degrees |

```bash
curl "https://prod.api.market/api/v1/quotalink/weather-api/current?latitude=51.5074&longitude=-0.1278" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "status": "success",
  "location": { "latitude": 51.49349, "longitude": -0.13172913 },
  "data": {
    "time": "2026-08-22T21:30",
    "interval": 900,
    "temperature_2m": 19.4,
    "apparent_temperature": 17.5,
    "relative_humidity_2m": 47,
    "wind_speed_10m": 9.4,
    "wind_direction_10m": 124,
    "weather_code": 1,
    "weather_description": "Mainly clear"
  },
  "units": { "temperature": "celsius", "wind": "kmh" }
}
```

#### GET /forecast

Seven day daily forecast. All arrays are parallel and share the `time` index.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `latitude` | query | number | Yes | Latitude in decimal degrees |
| `longitude` | query | number | Yes | Longitude in decimal degrees |

```bash
curl "https://prod.api.market/api/v1/quotalink/weather-api/forecast?latitude=51.5074&longitude=-0.1278" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "status": "success",
  "timezone": "Europe/London",
  "location": { "latitude": 51.49349, "longitude": -0.13172913 },
  "data": {
    "time": ["2026-08-22", "2026-08-23"],
    "temperature_2m_max": [22.0, 23.9],
    "temperature_2m_min": [12.7, 14.8],
    "precipitation_sum": [0.0, 0.0],
    "precipitation_probability_max": [33, 0],
    "wind_speed_10m_max": [15.1, 12.4],
    "weather_code": [1, 3],
    "weather_descriptions": ["Mainly clear", "Overcast"]
  }
}
```

#### GET /hourly

The next 24 hours, in the same parallel-array shape as `/forecast`.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `latitude` | query | number | Yes | Latitude in decimal degrees |
| `longitude` | query | number | Yes | Longitude in decimal degrees |

```bash
curl "https://prod.api.market/api/v1/quotalink/weather-api/hourly?latitude=51.5074&longitude=-0.1278" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "status": "success",
  "location": { "latitude": 51.49349, "longitude": -0.13172913 },
  "data": {
    "time": ["2026-08-22T22:00", "2026-08-22T23:00"],
    "temperature_2m": [19.9, 18.9],
    "precipitation_probability": [0, 0],
    "wind_speed_10m": [8.2, 7.6],
    "weather_code": [1, 1],
    "weather_descriptions": ["Mainly clear", "Mainly clear"]
  }
}
```

#### GET /air-quality

Pollutant concentrations and air quality indices.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `latitude` | query | number | Yes | Latitude in decimal degrees |
| `longitude` | query | number | Yes | Longitude in decimal degrees |

```bash
curl "https://prod.api.market/api/v1/quotalink/weather-api/air-quality?latitude=51.5074&longitude=-0.1278" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "status": "success",
  "location": { "latitude": 51.5, "longitude": -0.10000038 },
  "data": {
    "time": "2026-08-22T21:00",
    "interval": 3600,
    "pm2_5": 6.3,
    "pm10": 9.4,
    "ozone": 48.0,
    "nitrogen_dioxide": 25.2,
    "sulphur_dioxide": 1.3,
    "carbon_monoxide": 190.0,
    "european_aqi": 19,
    "us_aqi": 37
  }
}
```

Concentrations are in micrograms per cubic metre. `european_aqi` and `us_aqi` use different scales and are not interchangeable.

#### GET /geocode

Resolves a place name to coordinates so you can feed the weather endpoints.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `name` | query | string | Yes | Place name to search for |

```bash
curl "https://prod.api.market/api/v1/quotalink/weather-api/geocode?name=London" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "status": "success",
  "count": 5,
  "data": [
    {
      "id": 2643743,
      "name": "London",
      "latitude": 51.50853,
      "longitude": -0.12574,
      "country": "United Kingdom",
      "country_code": "GB",
      "admin1": "England",
      "admin2": "Greater London",
      "timezone": "Europe/London",
      "population": 8961989,
      "elevation": 25.0,
      "feature_code": "PPLC"
    }
  ]
}
```

Ambiguous names return several matches: London, UK and London, Ontario both appear for `London`. Use `country_code` and `population` to pick the right one.

#### GET /health

Service liveness. Takes no parameters and is useful for monitoring.

```bash
curl "https://prod.api.market/api/v1/quotalink/weather-api/health" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{ "service": "weather-api", "status": "ok", "upstream": "open-meteo" }
```

## Status Codes

| Code | Meaning | What to do |
| --- | --- | --- |
| `200` | Success | Parse the response body |
| `400` | Required parameters missing or the `x-api-market-key` header is absent | Use `latitude` and `longitude` in full, and check headers |
| `401` | Invalid or expired API key | Verify the key under Account → API Keys |
| `403` | Your subscription does not cover this endpoint | Check your active plan |
| `429` | Plan quota exhausted or rate limit exceeded | Back off and retry, or upgrade |
| `5xx` | Upstream weather provider error | Retry with exponential backoff |

## Rate Limits

Both plans allow up to **10 requests per second**. Quotas apply per billing period:

- **FREE**: 100 API units, hard limit. Requests are rejected once the quota is spent.
- **PRO**: 10,000 API units per month, hard limit.

Every endpoint costs one unit per request.

## Error Handling

Missing coordinates return a `400` naming the problem:

```json
{ "error": "latitude and longitude are required" }
```

The most common integration mistake is sending `lat` and `lon` instead of `latitude` and `longitude`. Check `status` on every response before reading `data`, and retry `5xx` responses with exponential backoff.

## Implementation Guide

### Example Code

```python
import requests

BASE = "https://prod.api.market/api/v1/quotalink/weather-api"
HEADERS = {"x-api-market-key": "YOUR_API_MARKET_KEY"}

def weather_for(place):
    geo = requests.get(f"{BASE}/geocode", params={"name": place},
                       headers=HEADERS, timeout=15).json()
    top = geo["data"][0]
    now = requests.get(f"{BASE}/current", headers=HEADERS, timeout=15,
                       params={"latitude": top["latitude"],
                               "longitude": top["longitude"]}).json()
    return top["name"], top["country"], now["data"]

name, country, data = weather_for("London")
print(f"{name}, {country}: {data['temperature_2m']}C, {data['weather_description']}")
```

```javascript
const BASE = "https://prod.api.market/api/v1/quotalink/weather-api";
const headers = { "x-api-market-key": process.env.API_MARKET_KEY };

async function sevenDay(latitude, longitude) {
  const url = `${BASE}/forecast?latitude=${latitude}&longitude=${longitude}`;
  const res = await fetch(url, { headers });
  if (!res.ok) throw new Error(`Forecast failed: ${res.status}`);
  const { data } = await res.json();
  return data.time.map((day, i) => ({
    day,
    high: data.temperature_2m_max[i],
    low: data.temperature_2m_min[i],
    summary: data.weather_descriptions[i],
    rainChance: data.precipitation_probability_max[i],
  }));
}
```

### Performance Optimization

- Geocode once and store the coordinates. Place names do not move, and caching them removes an entire call from every subsequent lookup.
- Match your cache TTL to the update interval: `/current` refreshes every 15 minutes (`interval: 900`) and `/air-quality` hourly (`interval: 3600`). Polling faster only spends quota.
- Round coordinates to three decimals before caching. The service snaps to a grid anyway, so nearby requests can share a cache entry.
- Fetch `/forecast` once or twice a day rather than per page view, and serve it from your own store.

## FAQ

**Do I need an account with QuotaLink or Open-Meteo to use this API?**

No. Your API.market key is the only credential required.

**Why do I get a 400 when I send `lat` and `lon`?**

The parameters must be spelled out as `latitude` and `longitude`.

**Why does the returned location differ from the coordinates I sent?**

Weather data is computed on a grid. The `location` object reports the centre of the nearest grid cell used for your request.

**What units are used?**

Temperature in Celsius, wind in km/h, precipitation in millimetres and pollutants in micrograms per cubic metre. `/current` echoes its units in the `units` object.

**How do I turn a weather code into an icon?**

Every response includes `weather_description` (or `weather_descriptions` for arrays) next to the code, so you can map from either.

**How far ahead does the forecast go?**

`/forecast` returns 7 days and `/hourly` returns the next 24 hours.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Free weather API with real-time forecasts, air quality index, and geocoding for any location worldwide. No API key required.