{"openapi":"3.1.0","info":{"title":"Xweather History And Roads (BYOK) API","version":"0.1.0","description":"Xweather History And Roads (BYOK) lets an AI assistant read your own Xweather History And Roads data through the Xweather History And Roads API with a key you supply (Xweather client id). Read-only: 8 tools (get_place, search_places, get_observation_summary, get_observation_archive, get_road_weather_conditions, get_road_weather_analytics, get_storm_report_summary, get_storm_cell_summary). The...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-xweather-history-roads.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-xweather-history-roads/docs"},"termsOfService":"https://connectorbay.com/byok-xweather-history-roads/terms"},"servers":[{"url":"https://byok-xweather-history-roads.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-xweather-history-roads/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_place":{"post":{"operationId":"get_place","summary":"Look up a place by name, coordinates, postal code or id: position, state, country, region, elevation, population, time z","description":"Look up a place by name, coordinates, postal code or id: position, state, country, region, elevation, population, time zone, weather zones and county ids. Use for \"What time zone and elevation does Minneapolis have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"place":{"description":"Place to query: 'city,state' such as 'minneapolis,mn', 'lat,lon' such as '44.98,-93.26', a US or Canadian postal code, an ICAO code or a place id.","maxLength":100,"title":"Place","type":"string"},"fields":{"anyOf":[{"maxLength":1500,"type":"string"},{"type":"null"}],"default":"loc.lat,loc.long,place.name,place.state,place.stateFull,place.country,place.countryFull,place.region,place.continent,profile.elevM,profile.pop,profile.tz,profile.tzname,profile.wxzone,profile.countyid","description":"Comma-separated response properties to keep, in dot notation; the default keeps position, administrative names, elevation, time zone and zones.","title":"Fields"}},"required":["place"],"title":"get_placeArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_places":{"post":{"operationId":"search_places","summary":"Search the Xweather places database (cities, stations, airports, points of interest) with an advanced query, for example","description":"Search the Xweather places database (cities, stations, airports, points of interest) with an advanced query, for example the largest cities of a state. Use for \"Which cities in Minnesota start with the letters Min\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Advanced filter as property:value pairs, comma for AND and semicolon for OR (numbers match at least the value, min:max for a range, ! for not equal). Example: name:^minn,country:us.","maxLength":200,"title":"Query","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Maximum number of places to return.","title":"Limit"},"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Sort as property or property:-1 for descending, for example pop:-1.","title":"Sort"},"fields":{"anyOf":[{"maxLength":1500,"type":"string"},{"type":"null"}],"default":"loc.lat,loc.long,place.name,place.state,place.stateFull,place.country,place.countryFull,place.region,place.continent,profile.elevM,profile.pop,profile.tz,profile.tzname,profile.wxzone,profile.countyid","description":"Comma-separated response properties to keep, in dot notation; the default keeps position, administrative names, elevation and time zone.","title":"Fields"}},"required":["query"],"title":"search_placesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_observation_summary":{"post":{"operationId":"get_observation_summary","summary":"Get daily summaries of the observations of the reporting stations near a place for a date range (up to one month per cal","description":"Get daily summaries of the observations of the reporting stations near a place for a date range (up to one month per call, back to 2011): temperature range, humidity, pressure, wind, precipitation and weather. Use for \"What was the daily weather summary at Minneapolis over the last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"place":{"description":"Place to query: 'city,state' such as 'minneapolis,mn', 'lat,lon' such as '44.98,-93.26', a US or Canadian postal code, an ICAO code or a place id.","maxLength":100,"title":"Place","type":"string"},"from_time":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Start date or time: now, a relative value such as -1day, or a date such as 2026-10-01.","title":"From Time"},"to_time":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"End date or time: now, a relative value such as +1day, or a date such as 2026-10-19.","title":"To Time"},"fields":{"anyOf":[{"maxLength":1500,"type":"string"},{"type":"null"}],"default":"id,dataSource,place.name,place.state,place.country,profile.tz,periods.summary.dateTimeISO,periods.summary.temp.maxC,periods.summary.temp.minC,periods.summary.temp.avgC,periods.summary.temp.maxF,periods.summary.temp.minF,periods.summary.temp.avgF,periods.summary.rh.avg,periods.summary.pressure.avgMB,periods.summary.wind.maxKPH,periods.summary.wind.gustKPH,periods.summary.wind.avgKPH,periods.summary.precip.totalMM,periods.summary.precip.totalIN,periods.summary.weather.phrase","description":"Comma-separated response properties to keep, in dot notation; the default keeps daily temperature, humidity, pressure, wind and precipitation.","title":"Fields"}},"required":["place"],"title":"get_observation_summaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_observation_archive":{"post":{"operationId":"get_observation_archive","summary":"Get every archived observation of one past day from the stations near a place (back to 2011): temperature, humidity, pre","description":"Get every archived observation of one past day from the stations near a place (back to 2011): temperature, humidity, pressure, wind, visibility, weather and precipitation. Use for \"What were the hourly weather observations at Chicago O'Hare on 2026-10-01\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"place":{"description":"Place to query: 'city,state' such as 'minneapolis,mn', 'lat,lon' such as '44.98,-93.26', a US or Canadian postal code, an ICAO code or a place id.","maxLength":100,"title":"Place","type":"string"},"from_time":{"description":"The day to read as a date such as 2026-10-01 (the whole local day is returned).","maxLength":30,"title":"From Time","type":"string"},"plimit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Maximum number of periods (time steps) to return per record.","title":"Plimit"},"fields":{"anyOf":[{"maxLength":1500,"type":"string"},{"type":"null"}],"default":"id,dataSource,place.name,place.state,place.country,profile.tz,periods.ob.dateTimeISO,periods.ob.tempC,periods.ob.tempF,periods.ob.humidity,periods.ob.pressureMB,periods.ob.windSpeedKPH,periods.ob.windDir,periods.ob.windGustKPH,periods.ob.visibilityKM,periods.ob.weather,periods.ob.precipMM,periods.ob.uvi","description":"Comma-separated response properties to keep, in dot notation; the default keeps temperature, humidity, pressure, wind, visibility and precipitation of each observation.","title":"Fields"}},"required":["place","from_time"],"title":"get_observation_archiveArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_road_weather_conditions":{"post":{"operationId":"get_road_weather_conditions","summary":"Get the road weather forecast at a place (US, Canada, Europe, Japan, Australia, New Zealand): a green, yellow or red dri","description":"Get the road weather forecast at a place (US, Canada, Europe, Japan, Australia, New Zealand): a green, yellow or red driving index, the road surface condition (dry, wet, snow, ice) and surface temperature, every 15 minutes for 2 hours then hourly for 24 hours. Counts as 5 accesses per call. Use for \"Will the roads be icy around Minneapolis tonight\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"place":{"description":"Place to query: 'city,state' such as 'minneapolis,mn', 'lat,lon' such as '44.98,-93.26', a US or Canadian postal code, an ICAO code or a place id.","maxLength":100,"title":"Place","type":"string"},"plimit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Maximum number of periods (time steps) to return per record.","title":"Plimit"},"fields":{"anyOf":[{"maxLength":1500,"type":"string"},{"type":"null"}],"default":"id,dataSource,road.type,road.name,loc.lat,loc.long,place.name,place.state,periods.dateTimeISO,periods.summary,periods.summaryIndex,periods.roadSurface.condition,periods.roadSurface.tempC,periods.roadSurface.tempF","description":"Comma-separated response properties to keep, in dot notation; the default keeps driving index, surface condition and temperature.","title":"Fields"}},"required":["place"],"title":"get_road_weather_conditionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_road_weather_analytics":{"post":{"operationId":"get_road_weather_analytics","summary":"Get the full road weather forecast at a place: surface condition and temperature plus water film, snow and ice thickness","description":"Get the full road weather forecast at a place: surface condition and temperature plus water film, snow and ice thickness and probabilities of truck rollover, hydroplaning, fog and blowing snow. Counts as 10 accesses per call. Use for \"What is the hydroplaning and fog risk on the roads around Seattle tonight\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"place":{"description":"Place to query: 'city,state' such as 'minneapolis,mn', 'lat,lon' such as '44.98,-93.26', a US or Canadian postal code, an ICAO code or a place id.","maxLength":100,"title":"Place","type":"string"},"plimit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Maximum number of periods (time steps) to return per record.","title":"Plimit"},"fields":{"anyOf":[{"maxLength":1500,"type":"string"},{"type":"null"}],"default":"id,dataSource,road.type,road.name,loc.lat,loc.long,place.name,place.state,periods.dateTimeISO,periods.summary,periods.summaryIndex,periods.roadSurface.condition,periods.roadSurface.tempC,periods.roadSurface.tempF,periods.roadSurface.waterFilmThicknessMM,periods.roadSurface.snowThicknessCM,periods.roadSurface.iceThicknessMM,periods.riskProbability.truckRollover,periods.riskProbability.hydroplane,periods.riskProbability.lowVisFog,periods.riskProbability.lowVisBlowingSnow","description":"Comma-separated response properties to keep, in dot notation; the default keeps surface condition, thicknesses and risk probabilities.","title":"Fields"}},"required":["place"],"title":"get_road_weather_analyticsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_storm_report_summary":{"post":{"operationId":"get_storm_report_summary","summary":"Summarise the US local storm reports that match a query and time range: how many reports, per type and per state, with m","description":"Summarise the US local storm reports that match a query and time range: how many reports, per type and per state, with maximum hail size or wind speed. Use for \"How many tornado and hail reports were there in Oklahoma in the last 7 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Advanced filter as property:value pairs, comma for AND and semicolon for OR (numbers match at least the value, min:max for a range, ! for not equal). Example: state:ok.","maxLength":200,"title":"Query","type":"string"},"filter":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Report types to include, comma separated, such as hail, tornado, wind, flood or snow.","title":"Filter"},"from_time":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Start date or time: now, a relative value such as -1day, or a date such as 2026-10-01.","title":"From Time"},"to_time":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"End date or time: now, a relative value such as +1day, or a date such as 2026-10-19.","title":"To Time"},"fields":{"anyOf":[{"maxLength":1500,"type":"string"},{"type":"null"}],"default":"summary.range.count,summary.range.fromDateTimeISO,summary.range.toDateTimeISO,summary.states,summary.typeCats,summary.types","description":"Comma-separated response properties to keep, in dot notation; the default keeps report counts by type and state.","title":"Fields"}},"required":["query"],"title":"get_storm_report_summaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_storm_cell_summary":{"post":{"operationId":"get_storm_cell_summary","summary":"Summarise the current US storm cells within a radius of a place: how many, with hail probability and size, tornadic sign","description":"Summarise the current US storm cells within a radius of a place: how many, with hail probability and size, tornadic signatures, rotation, cell top and intensity. Use for \"How many severe storm cells are within 50 miles of Dallas\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"place":{"description":"Place to query: 'city,state' such as 'minneapolis,mn', 'lat,lon' such as '44.98,-93.26', a US or Canadian postal code, an ICAO code or a place id.","maxLength":100,"title":"Place","type":"string"},"radius":{"anyOf":[{"maxLength":12,"type":"string"},{"type":"null"}],"default":null,"description":"Search radius around the place with a unit, for example 25miles or 50km (default set by the service).","title":"Radius"},"query":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Advanced filter as property:value pairs, comma for AND and semicolon for OR (numbers match at least the value, min:max for a range, ! for not equal). Example: hail:80.","title":"Query"},"fields":{"anyOf":[{"maxLength":1500,"type":"string"},{"type":"null"}],"default":"summary.range.count,summary.range.fromDateTimeISO,summary.range.toDateTimeISO,summary.tvs.count,summary.mda.threatCount,summary.hail.prob.max,summary.hail.probSevere.max,summary.hail.maxSize.maxIN,summary.vil.max,summary.top.maxFT","description":"Comma-separated response properties to keep, in dot notation; the default keeps cell counts, hail, rotation and intensity.","title":"Fields"}},"required":["place"],"title":"get_storm_cell_summaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}