meteoblue APImeteoblue.com ↗
Search meteoblue locations and retrieve 14-day daily forecasts, current conditions, and 3-hourly breakdowns via two structured JSON endpoints.
What is the meteoblue API?
The meteoblue API provides two endpoints — search_locations and get_weather_forecast — covering meteoblue's global location database and up to 14 days of daily forecast data per place. A single call to get_weather_forecast returns over 20 fields including max/min temperature, wind speed, precipitation range, sunshine hours, predictability scores, current conditions, and 3-hourly detail for any selected forecast day, all in metric units.
curl -X GET 'https://api.parse.bot/scraper/410af4ea-a421-4e12-99b0-47abb05f63ce/search_locations?query=Chengdu' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace meteoblue-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: meteoblue Weather SDK — search locations, fetch forecasts."""
from parse_apis.meteoblue_com_api import Meteoblue, LocationNotFound
client = Meteoblue()
# Search for locations matching a city name; cap total results.
location = client.locations.search(query="Chengdu", limit=1).first()
if location is None:
raise SystemExit("No locations found for query")
print(f"{location.name}, {location.admin1}, {location.country}")
print(f" slug: {location.location_slug} pop: {location.population}")
# Fetch the full 14-day forecast for the discovered location.
forecast = location.get_forecast()
print(f"\nCurrent: {forecast.current.temperature}{forecast.current.temperature_unit}, {forecast.current.condition}")
print(f"Units — temp: {forecast.units.temperature}, wind: {forecast.units.wind_speed}, precip: {forecast.units.precipitation}")
# Walk the daily outlook.
for day in forecast.daily[:5]:
print(f" {day.date} ({day.weekday}): {day.temperature_min}-{day.temperature_max}, "
f"wind {day.wind_speed} {day.wind_direction}, precip {day.precipitation}, "
f"sun {day.sunshine_hours}h, predictability {day.predictability}")
# Drill into 3-hourly detail for a specific day.
detail = location.get_forecast(day=3)
print(f"\n3-hourly for {detail.selected_date}:")
for hour in detail.three_hourly:
print(f" {hour.time}: {hour.temperature}° (feels {hour.felt_temperature}°), "
f"{hour.condition}, precip prob {hour.precipitation_probability_pct}%")
# Point lookup by slug with error handling for an unknown location.
try:
remote = client.location("nonexistent_nowhere_0").get_forecast()
except LocationNotFound:
print("\nLocationNotFound raised for unknown slug — handled gracefully")
print("\nexercised: locations.search / get_forecast / LocationNotFound")
Searches meteoblue's location database by place name and returns matching places ranked by the site's relevance ranking, 10 per page. Each result carries location_slug, the identifier consumed by get_weather_forecast, plus coordinates, altitude, IANA timezone, country and administrative region. Paginated via page (default 1); pages and total_count come from the site, has_more is true while further pages exist. A query with no matches returns an empty results array with total_count 0.
| Param | Type | Description |
|---|---|---|
| page | integer | 1-based result page; each page holds 10 results. |
| queryrequired | string | Free-text place name to search for (city, town, airport). Partial names are matched. |
{
"type": "object",
"fields": {
"page": "integer, current page",
"pages": "integer, total number of pages reported by the site",
"query": "the search text as echoed by the site",
"results": "array of location records: location_slug (string identifier for get_weather_forecast), location_id (integer), name, admin1 (region), country, country_code (ISO-2), latitude, longitude, altitude_m (metres above sea level), timezone (IANA), population, iata/icao (airport codes, null when none), feature_code (GeoNames feature code)",
"has_more": "boolean, true when page < pages",
"total_count": "integer, total matching locations reported by the site"
},
"sample": {
"data": {
"page": 2,
"pages": 67,
"query": "Yong'an",
"results": [
{
"iata": null,
"icao": null,
"name": "Yong'an",
"admin1": "Taipei",
"country": "Taiwan",
"latitude": 25.0781,
"timezone": "Asia/Taipei",
"longitude": 121.467,
"altitude_m": 11,
"population": 0,
"location_id": 11700441,
"country_code": "TW",
"feature_code": "PPLA4",
"location_slug": "yong%27an_taiwan_11700441"
},
{
"iata": null,
"icao": null,
"name": "Yongan",
"admin1": "Jeollabuk-do",
"country": "South Korea",
"latitude": 36.1196,
"timezone": "Asia/Seoul",
"longitude": 126.953,
"altitude_m": 21,
"population": 0,
"location_id": 1832642,
"country_code": "KR",
"feature_code": "PPLA3",
"location_slug": "yongan_south-korea_1832642"
}
],
"has_more": true,
"total_count": 662
},
"status": "success"
}
}About the meteoblue API
Endpoints Overview
The API exposes two endpoints. search_locations accepts a free-text query (city name, town, or airport) and returns up to 10 matching places per page, ranked by meteoblue's relevance. Each result includes a location_slug — the identifier required by the second endpoint — alongside location_id, name, admin1 (region), country, coordinates, altitude, and IANA timezone. Pagination is handled via the page parameter; the response also returns total_count and has_more so callers can determine whether additional pages exist.
Forecast Data
get_weather_forecast takes a location_slug exactly as emitted by search_locations and returns a single structured response covering four data layers: location metadata (name, region, country, latitude, longitude, altitude in metres, timezone abbreviation), current conditions (temperature, condition text, local time at the location), a daily array of 14 records, and a three_hourly array for one selected day. Each daily record includes the date, weekday, daytime and nighttime condition labels, temperature max and min, wind speed, precipitation range, sunshine hours, and a predictability figure. Units for temperature, wind speed, and precipitation are named in a units object.
3-Hourly Detail
The optional day parameter (1–14) controls which day's 3-hourly breakdown is returned in three_hourly. Each 3-hourly record carries an ISO-8601 timestamp with UTC offset, condition label, temperature, felt temperature, and wind direction. If day is omitted, the response defaults to day 1 (today). The selected_day integer and selected_date ISO date fields in the response confirm which day the three_hourly data corresponds to.
Coverage and Units
All temperature values are in Celsius, wind speed in km/h, and precipitation in millimetres, as labelled in the units object. Location coverage follows meteoblue's global database; the search endpoint matches partial names, making it straightforward to resolve ambiguous place names before fetching a forecast.
The meteoblue API is a managed, monitored endpoint for meteoblue.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when meteoblue.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official meteoblue.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Displaying a 14-day daily weather outlook in a travel planning app using temperature_max, temperature_min, and condition_day fields
- Building a wind and precipitation dashboard for outdoor event scheduling using wind_speed and precipitation range from the daily array
- Resolving user-entered city names to precise meteoblue location_slugs before fetching forecasts via search_locations
- Showing current local conditions (temperature, condition text, local time) on a location-aware widget using the current object
- Rendering intraday 3-hourly forecasts for a selected date using felt_temperature, wind_direction, and condition from three_hourly
- Comparing sunshine hours across multiple locations for solar energy planning using the sunshine_hours field in daily records
- Alerting users to low forecast predictability scores before a trip using the predictability field in the 14-day daily array
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.