API Documentation

Access weather, climate, terrain, environment, hazard, and proximity data for any coordinates on Earth. All responses are JSON.

🔑 Authentication

All API requests require an API key. You can get one from the PixelGust dashboard under your account settings.

Pass your key via header (recommended) or query parameter:

          # Header (recommended)
curl -H "X-API-Key: YOUR_API_KEY" \
  https://pixelgust.com/v1/weather?lat=37.97&lon=23.73

# Query parameter
curl https://pixelgust.com/v1/weather?lat=37.97&lon=23.73&api_key=YOUR_API_KEY
        

⏱️ Rate Limits

Rate limits are applied per API key based on your subscription tier:

Tier	Daily Calls	Burst (per min)	Polygon Area
Free	50	10	—
Basic	500	30	≤ 5,000 km²
Pro	5,000	120	≤ 50,000 km²
Enterprise	50,000	Unlimited	≤ 150,000 km²

Rate-limited responses return 429 with Retry-After header.

Base URL

https://pixelgust.com/v1

GET /v1/weather

Get current weather conditions (GFS nowcast) for a point. Returns temperature, humidity, precipitation, wind, pressure, cloud cover, solar radiation, and more.

Parameter	Type		Description
`lat`	float	required	Latitude (-90 to 90)
`lon`	float	required	Longitude (-180 to 180)

          Example Request
curl -H "X-API-Key: YOUR_KEY" \
  "https://pixelgust.com/v1/weather?lat=40.64&lon=22.94"
        

          Response
{
  "temperature_c": 18.5,
  "humidity_pct": 62,
  "wind_speed_ms": 3.2,
  "wind_direction_deg": 245,
  "precipitation_mm": 0,
  "pressure_hpa": 1013.2,
  "cloud_cover_pct": 45,
  "solar_radiation_mj": 12.8,
  "dewpoint_c": 10.8
}
        

GET /v1/weather/forecast

Get weather forecast for a point. Supports up to 7 days ahead. Requires Basic tier or above.

Parameter	Type		Description
`lat`	float	required	Latitude
`lon`	float	required	Longitude
`day`	int	optional	Forecast day: 0 = today, 1 = tomorrow, ... up to 7. Default: 0

          Example
curl -H "X-API-Key: YOUR_KEY" \
  "https://pixelgust.com/v1/weather/forecast?lat=40.64&lon=22.94&day=2"
        

GET /v1/weather/historical

Get historical weather averages (ERA5 reanalysis, 2015–2024) for a point. Optionally filter by month. Requires Basic tier or above.

Parameter	Type		Description
`lat`	float	required	Latitude
`lon`	float	required	Longitude
`month`	int	optional	Month (1–12) for monthly average. Omit for annual average.

          Example
curl -H "X-API-Key: YOUR_KEY" \
  "https://pixelgust.com/v1/weather/historical?lat=40.64&lon=22.94&month=7"
        

GET /v1/terrain

Get terrain data for a point including elevation, slope, aspect, and topographic wetness index (TWI).

Parameter	Type		Description
`lat`	float	required	Latitude
`lon`	float	required	Longitude

          Response
{
  "lat": 40.64,
  "lon": 22.94,
  "terrain": {
    "elevation_m": 42,
    "slope_deg": 2.3,
    "aspect_deg": 180,
    "twi": 8.7
  }
}
        

GET /v1/hazards

Get hazard assessment for a point including soil erosion risk (RUSLE model) and flood susceptibility (TWI-based).

Parameter	Type		Description
`lat`	float	required	Latitude
`lon`	float	required	Longitude

          Response
{
  "lat": 40.64,
  "lon": 22.94,
  "hazards": {
    "rusle_t_ha_yr": 1.8,
    "erosion_class": "Low",
    "flood_twi": {
      "twi_value": 8.7,
      "susceptibility": "Moderate"
    }
  }
}
        

GET /v1/environment

Get environmental data including NDVI (vegetation index), evapotranspiration, and land cover classification.

Parameter	Type		Description
`lat`	float	required	Latitude
`lon`	float	required	Longitude

          Response
{
  "lat": 40.64,
  "lon": 22.94,
  "environment": {
    "ndvi": 0.42,
    "evapotranspiration_mm": 3.8,
    "land_cover": "Urban",
    "land_cover_code": 50
  }
}
        

GET /v1/proximity

Get nearest features including cities, water bodies, coastline, airports, protected areas, and more.

Parameter	Type		Description
`lat`	float	required	Latitude
`lon`	float	required	Longitude

          Response
{
  "lat": 40.64,
  "lon": 22.94,
  "proximity": {
    "nearest_city": { "name": "Thessaloniki", "distance_km": 1.2 },
    "nearest_coast": { "distance_km": 3.8 },
    "nearest_airport": { "name": "SKG", "distance_km": 14.5 },
    "nearest_water": { "name": "Thermaikos Gulf", "distance_km": 3.8 }
  }
}
        

POST /v1/polygon/stats

Compute zonal statistics (weather, terrain, hazard, environment) for a polygon area. Coordinates are [longitude, latitude] pairs. Max area depends on tier.

Request Body (JSON)

Field	Type		Description
`coordinates`	array	required	Array of [lon, lat] pairs forming a closed polygon
`mode`	string	optional	`nowcast` (default), `forecast`, or omit for historical
`day`	int	optional	Forecast day (0–7), used when mode is `forecast`
`month`	int	optional	Month (1–12) for historical monthly average

          Example Request
curl -X POST "https://pixelgust.com/v1/polygon/stats" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "coordinates": [
      [23.7, 37.9],
      [23.8, 37.9],
      [23.8, 38.0],
      [23.7, 38.0],
      [23.7, 37.9]
    ],
    "mode": "nowcast"
  }'
        

GET /v1/usage

Check your current daily API usage, tier, and remaining quota.

          Response
{
  "tier": "basic",
  "daily_usage": 42,
  "daily_limit": 500,
  "remaining": 458,
  "polygon_limits": {
    "max_vertices": 100,
    "max_area_km2": 5000
  }
}
        

Error Codes

All errors return a JSON object with a detail field.

Status	Meaning
`401`	Missing or invalid API key
`400`	Invalid parameters (e.g., polygon too large or too many vertices)
`429`	Rate limit exceeded — check `Retry-After` header
`500`	Server error — data unavailable for the requested location
`503`	Service temporarily unavailable