@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Weatherbit - Interactive Swagger UI Documentation
@base https://api.weatherbit.io/v2.0
@version 2.0.0
@auth ApiKey key in query
@common_fields {key: any # Your registered API key., lat: any # Latitude component of location., lon: any # Longitude component of location.}
@endpoints 18
@toc alerts(1), current(3), history(7), forecast(6), normals(1)

@group alerts
@endpoint GET /alerts
@desc Returns severe weather alerts issued by meteorological agencies - Given a lat/lon.
@optional {city_id: any # City ID. Example: 4487042, city: any # City search.. Example - &city=Raleigh,NC or &city=Berlin,DE or city=Paris&country=FR, postal_code: any # Postal Code. Example: 28546, country: any # Country Code (2 letter) - to be used with postal_code., station: any # Station Call ID.}
@returns(200) Weather Alert Object.
@returns(204) No Data Found
@errors {400: Client Error, 403: Unauthorized/No Access for current plan level, 429: Daily or Velocity limit exceeded, 500: Internal Server Error}

@endgroup

@group current
@endpoint GET /current
@desc Returns a Current Observation - Given a lat/lon.
@optional {include: any # Include 1 hour - minutely precip forecast in the response, or severe weather alerts, city_id: any # City ID. Example: 4487042, city: any # City search.. Example - &city=Raleigh,NC or &city=Berlin,DE or city=Paris&country=FR, postal_code: any # Postal Code. Example: 28546, country: any # Country Code (2 letter) - to be used with postal_code., station: any # Station Call ID., stations: any # Comma separated list of Station Call ID's. Example: KRDU,KBFI,KVNY, points: any # Comma separated list of points. Example: (35.5, -75.5),(45, 65),(45.12, -130.5), cities: any # Comma separated list of City ID's. Example: 4487042, 4494942, 4504871, units: any # Convert to units. Default Metric See units field description, lang: any # Language (Default: English) See language field description}
@returns(200) An Observation Group object.
@returns(204) No Data Found
@errors {400: Client Error, 403: Unauthorized/No Access for current plan level, 429: Daily or Velocity limit exceeded, 500: Internal Server Error}

@endgroup

@group history
@endpoint GET /history/lightning
@desc Returns lightning data by lat/lon from a given date.
@required {date: any # Date to retrieve data for. (YYYY-MM-DD)}
@optional {limit: any # Limit result lightning. (Default 1500, Max 2500), skip: any # Number of results to skip in response. (Offset), search_distance_km: any # Radial search distance from point in KM. (Default 20 KM - Max 75 KM), sort: any # Sort results by either most recent occurrence, or least distance from point. (Default distance), output_type: any # Data type of reponse JSON or GeoJSON. Default JSON., tz: any # Assumed timezone option to use for date parameter. Default is local.}
@returns(200) Lightning data.
@returns(204) No Data Found
@errors {400: Client Error, 403: Unauthorized/No Access for current plan level, 429: Daily or Velocity limit exceeded, 500: Internal Server Error}

@endgroup

@group current
@endpoint GET /current/lightning
@desc Returns nearest and most recent lightning observations - Given a lat/lon.
@optional {limit: any # Limit result lightning. (Default 20), skip: any # Number of results to skip in response. (Offset), search_distance_km: any # Radial search distance from point in KM. (Default 20 KM - Max 75 KM), search_mins: any # Search time backwards from current time in minutes. (Default 30 minutes - Max 45 minutes), sort: any # Sort results by either most recent occurrence, or least distance from point. (Default distance), output_type: any # Data type of reponse JSON or GeoJSON. Default JSON.}
@returns(200) Lightning data.
@returns(204) No Data Found
@errors {400: Client Error, 403: Unauthorized/No Access for current plan level, 429: Daily or Velocity limit exceeded, 500: Internal Server Error}

@endgroup

@group forecast
@endpoint GET /forecast/daily
@desc Returns a daily forecast - Given Lat/Lon.
@optional {city_id: any # City ID. Example: 4487042, city: any # City search.. Example - &city=Raleigh,NC or &city=Berlin,DE or city=Paris&country=FR, postal_code: any # Postal Code. Example: 28546, country: any # Country Code (2 letter) - to be used with postal_code., station: any # Station Call ID., days: any # Number of days to return. Default 16., units: any # Convert to units. Default Metric See units field description, lang: any # Language (Default: English) See language field description}
@returns(200) A forecast object.
@returns(204) No Data Found
@errors {400: Client Error, 403: Unauthorized/No Access for current plan level, 429: Daily or Velocity limit exceeded, 500: Internal Server Error}

@endpoint GET /forecast/minutely
@desc Returns a 60 minute precipitation forecast - Given Lat/Lon.
@optional {city_id: any # City ID. Example: 4487042, city: any # City search.. Example - &city=Raleigh,NC or &city=Berlin,DE or city=Paris&country=FR, postal_code: any # Postal Code. Example: 28546, country: any # Country Code (2 letter) - to be used with postal_code., station: any # Station Call ID., units: any # Convert to units. Default Metric See units field description}
@returns(200) A forecast object.
@returns(204) No Data Found
@errors {400: Client Error, 403: Unauthorized/No Access for current plan level, 429: Daily or Velocity limit exceeded, 500: Internal Server Error}

@endpoint GET /forecast/airquality
@desc Returns 72 hour (hourly) Air Quality forecast - Given a geolocation.
@optional {city_id: any # City ID. Example: 4487042, city: any # City search.. Example - &city=Raleigh,NC or &city=Berlin,DE or city=Paris&country=FR, postal_code: any # Postal Code. Example: 28546, country: any # Country Code (2 letter) - to be used with postal_code., hours: any # Number of hours to return.}
@returns(200) A forecast object.
@returns(204) No Data Found
@errors {400: Client Error, 403: Unauthorized/No Access for current plan level, 429: Daily or Velocity limit exceeded, 500: Internal Server Error}

@endgroup

@group history
@endpoint GET /history/airquality
@desc Returns 72 hours of historical air quality conditions - Given a geolocation.
@optional {city_id: any # City ID. Example: 4487042, city: any # City search.. Example - &city=Raleigh,NC or &city=Berlin,DE or city=Paris&country=FR, postal_code: any # Postal Code. Example: 28546, country: any # Country Code (2 letter) - to be used with postal_code.}
@returns(200) Historical air quality conditions
@returns(204) No Data Found
@errors {400: Client Error, 403: Unauthorized/No Access for current plan level, 429: Daily or Velocity limit exceeded, 500: Internal Server Error}

@endgroup

@group current
@endpoint GET /current/airquality
@desc Returns current air quality conditions - Given a geolocation.
@optional {city_id: any # City ID. Example: 4487042, city: any # City search.. Example - &city=Raleigh,NC or &city=Berlin,DE or city=Paris&country=FR, postal_code: any # Postal Code. Example: 28546, country: any # Country Code (2 letter) - to be used with postal_code.}
@returns(200) Current air quality conditions
@returns(204) No Data Found
@errors {400: Client Error, 403: Unauthorized/No Access for current plan level, 429: Daily or Velocity limit exceeded, 500: Internal Server Error}

@endgroup

@group forecast
@endpoint GET /forecast/hourly
@desc Returns an hourly forecast - Given a lat/lon.
@optional {city_id: any # City ID. Example: 4487042, city: any # City search.. Example - &city=Raleigh,NC or &city=Berlin,DE or city=Paris&country=FR, postal_code: any # Postal Code. Example: 28546, country: any # Country Code (2 letter) - to be used with postal_code., station: any # Station Call ID., units: any # Convert to units. Default Metric See units field description, lang: any # Language (Default: English) See language field description, hours: any # Number of hours to return.}
@returns(200) A forecast object.
@returns(204) No Data Found
@errors {400: Client Error, 403: Unauthorized/No Access for current plan level, 429: Daily or Velocity limit exceeded, 500: Internal Server Error}

@endpoint GET /forecast/agweather
@desc Returns Agweather Forecast - Given a lat/lon.
@required {start_date: any # Start Date (YYYY-MM-DD or YYYY-MM-DD:HH)., end_date: any # End Date (YYYY-MM-DD or YYYY-MM-DD:HH).}
@optional {units: any # Convert to units. Default Metric See units field description}
@returns(200) An AGWeather Forecast Data Object.
@returns(204) No Data Found
@errors {400: Client Error, 403: Unauthorized/No Access for current plan level, 429: Daily or Velocity limit exceeded, 500: Internal Server Error}

@endgroup

@group history
@endpoint GET /history/agweather
@desc Returns Historical Agweather - Given a lat/lon.
@required {start_date: any # Start Date (YYYY-MM-DD or YYYY-MM-DD:HH)., end_date: any # End Date (YYYY-MM-DD or YYYY-MM-DD:HH)., tp: any # Time period of calculation (daily [DEFAULT], or hourly).}
@optional {units: any # Convert to units. Default Metric See units field description}
@returns(200) An AGWeather Historical Data Object.
@returns(204) No Data Found
@errors {400: Client Error, 403: Unauthorized/No Access for current plan level, 429: Daily or Velocity limit exceeded, 500: Internal Server Error}

@endgroup

@group normals
@endpoint GET /normals
@desc Returns Historical Climate Normals (Averages) - Given a lat/lon.
@required {start_day: any # Start Day (MM-DD)., end_day: any # End Day (MM-DD)., tp: any # Time period of calculation (daily, monthly, or hourly)., series_year: any # Series year for calculation. 2020 for 1991-2020. 2010 for 1981-2010.}
@optional {units: any # Convert to units. Default Metric See units field description}
@returns(200) An Normals Data Object.
@returns(204) No Data Found
@errors {400: Client Error, 403: Unauthorized/No Access for current plan level, 429: Daily or Velocity limit exceeded, 500: Internal Server Error}

@endgroup

@group history
@endpoint GET /history/daily
@desc Returns Historical Observations - Given a lat/lon.
@required {start_date: any # Start Date (YYYY-MM-DD or YYYY-MM-DD:HH)., end_date: any # End Date (YYYY-MM-DD or YYYY-MM-DD:HH).}
@optional {city_id: any # City ID. Example: 4487042, city: any # City search.. Example - &city=Raleigh,NC or &city=Berlin,DE or city=Paris&country=FR, postal_code: any # Postal Code. Example: 28546, country: any # Country Code (2 letter) - to be used with postal_code., station: any # Station Call ID., units: any # Convert to units. Default Metric See units field description, lang: any # Language (Default: English) See language field description}
@returns(200) An Historical Day Data Object.
@returns(204) No Data Found
@errors {400: Client Error, 403: Unauthorized/No Access for current plan level, 429: Daily or Velocity limit exceeded, 500: Internal Server Error}

@endpoint GET /history/hourly
@desc Returns Historical Observations - Given a lat/lon.
@required {start_date: any # Start Date (YYYY-MM-DD or YYYY-MM-DD:HH)., end_date: any # End Date (YYYY-MM-DD or YYYY-MM-DD:HH).}
@optional {city_id: any # City ID. Example: 4487042, city: any # City search.. Example - &city=Raleigh,NC or &city=Berlin,DE or city=Paris&country=FR, postal_code: any # Postal Code. Example: 28546, country: any # Country Code (2 letter) - to be used with postal_code., station: any # Station Call ID., units: any # Convert to units. Default Metric See units field description, lang: any # Language (Default: English) See language field description, tz: any # Assume utc (default) or local time for start_date, end_date}
@returns(200) An Historical Data Object.
@returns(204) No Data Found
@errors {400: Client Error, 403: Unauthorized/No Access for current plan level, 429: Daily or Velocity limit exceeded, 500: Internal Server Error}

@endpoint GET /history/subhourly
@desc Returns Historical Observations - Given a lat/lon.
@required {start_date: any # Start Date (YYYY-MM-DD or YYYY-MM-DD:HH)., end_date: any # End Date (YYYY-MM-DD or YYYY-MM-DD:HH).}
@optional {city_id: any # City ID. Example: 4487042, city: any # City search.. Example - &city=Raleigh,NC or &city=Berlin,DE or city=Paris&country=FR, postal_code: any # Postal Code. Example: 28546, country: any # Country Code (2 letter) - to be used with postal_code., station: any # Station Call ID., units: any # Convert to units. Default Metric See units field description, lang: any # Language (Default: English) See language field description, tz: any # Assume utc (default) or local time for start_date, end_date}
@returns(200) An Historical Data Object.
@returns(204) No Data Found
@errors {400: Client Error, 403: Unauthorized/No Access for current plan level, 429: Daily or Velocity limit exceeded, 500: Internal Server Error}

@endgroup

@group forecast
@endpoint GET /forecast/energy
@desc Returns Energy Forecast API response  - Given a single lat/lon.
@optional {threshold: any # Temperature threshold to use to calculate degree days (default 18 C), units: any # Convert to units. Default Metric See units field description, tp: any # Time period (default: daily)}
@returns(200) An Energy Data Object.
@returns(204) No Data Found
@errors {400: Client Error, 403: Unauthorized/No Access for current plan level, 429: Daily or Velocity limit exceeded, 500: Internal Server Error}

@endgroup

@group history
@endpoint GET /history/energy
@desc Returns Energy API response  - Given a single lat/lon.
@required {start_date: any # Start Date (YYYY-MM-DD or YYYY-MM-DD:HH)., end_date: any # End Date (YYYY-MM-DD or YYYY-MM-DD:HH).}
@optional {tp: any # Time period to aggregate by (daily, monthly), threshold: any # Temperature threshold to use to calculate degree days (default 18 C), units: any # Convert to units. Default Metric See units field description}
@returns(200) An Energy Data Object.
@returns(204) No Data Found
@errors {400: Client Error, 403: Unauthorized/No Access for current plan level, 429: Daily or Velocity limit exceeded, 500: Internal Server Error}

@endgroup

@end