Weather API from Mashape

This is a sample spec that describes a Mashape Weather API. This example demonstrates features in the Swagger-2.0 specification as rendered with SwaggerHub. This output is part of the [Documenting REST APIs course](https://idratherbewriting.com/learnapidoc) on I'd Rather Be Writing. This Weather API displays forecast data by latitude and longitude. It's a simple weather API, but the data comes from Yahoo Weather Service. The weatherdata endpoint delivers the most robust package of information of the endpoints here. To explore the API, you'll need an API key. You can sign up for an API through Mashape, or you can just use this one\: `EF3g83pKnzmshgoksF83V6JB6QyTp1cGrrdjsnczTkkYgYrp8p`. For the latitude and longitude parameters, you can get this information from the URL of a location on Google Maps. For example, for Santa Clara, California, use the following\: * **lat**: `37.3708698` * **lng**: `-122.037593`
Contact Info: [email protected]
Version: 2.2
Apache 2.0
http://www.apache.org/licenses/LICENSE-2.0.html

Access

  1. APIKey KeyParamName:X-Mashape-Key KeyInQuery:false KeyInHeader:true

Methods

[ Jump to Models ]

Table of Contents

AirQuality

WeatherData

WeatherForecast

AirQuality

Up
get /aqi
Gets the air quality index (getAqi)
Air quality is a measure of air pollution. The higher the number, the worse the pollution.

Query parameters

lat (required)
Query Parameter — latitude
lng (required)
Query Parameter — longitude

Return type

aqiResponse

Example data

Content-Type: application/text
52

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

Responses

200

AQI response aqiResponse

Example data

Content-Type: application/text
52

WeatherData

Up
get /weatherdata
Get the full weather forecast with abundant details (getWeatherData)
Includes full details of the weather forecast, in JSON format. Details include everything from temperature to wind conditions, humidity, pressure, astronomy, conditions, sunset, high/lows, and future forecast.

Query parameters

lat (required)
Query Parameter — latitude
lng (required)
Query Parameter — longitude

Return type

weatherdata response

Example data

Content-Type: application/json
{
  "query" : {
    "count" : 1,
    "created" : "2017-06-24T23:47:36Z",
    "lang" : "en-US",
    "results" : {
      "channel" : {
        "units" : {
          "distance" : "km",
          "pressure" : "mb",
          "speed" : "km/h",
          "temperature" : "C"
        },
        "title" : "Yahoo! Weather - Sunnyvale, CA, US",
        "link" : "http://us.rd.yahoo.com/dailynews/rss/weather/Country__Country/*https://weather.yahoo.com/country/state/city-91990359/",
        "description" : "Yahoo! Weather for Sunnyvale, CA, US",
        "language" : "en-us",
        "lastBuildDate" : "Sat, 24 Jun 2017 04:47 PM PDT",
        "ttl" : "60",
        "location" : {
          "city" : "Sunnyvale",
          "country" : "United States",
          "region" : " CA"
        },
        "wind" : {
          "chill" : "73",
          "direction" : "345",
          "speed" : "28.97"
        },
        "atmosphere" : {
          "humidity" : "64",
          "pressure" : "34033.22",
          "rising" : "0",
          "visibility" : "25.91"
        },
        "astronomy" : {
          "sunrise" : "5:48 am",
          "sunset" : "8:33 pm"
        },
        "image" : {
          "title" : "Yahoo! Weather",
          "width" : "142",
          "height" : "18",
          "link" : "http://weather.yahoo.com",
          "url" : "http://l.yimg.com/a/i/brand/purplelogo//uh/us/news-wea.gif"
        },
        "item" : {
          "title" : "Conditions for Sunnyvale, CA, US at 04:00 PM PDT",
          "lat" : "37.377499",
          "long" : "-122.04686",
          "link" : "http://us.rd.yahoo.com/dailynews/rss/weather/Country__Country/*https://weather.yahoo.com/country/state/city-91990359/",
          "pubDate" : "Sat, 24 Jun 2017 04:00 PM PDT",
          "condition" : {
            "code" : "28",
            "date" : "Sat, 24 Jun 2017 04:00 PM PDT",
            "temp" : "22",
            "text" : "Mostly Cloudy"
          },
          "forecast" : [ {
            "code" : "28",
            "date" : "24 Jun 2017",
            "day" : "Sat",
            "high" : "25",
            "low" : "16",
            "text" : "Mostly Cloudy"
          }, {
            "code" : "30",
            "date" : "25 Jun 2017",
            "day" : "Sun",
            "high" : "25",
            "low" : "15",
            "text" : "Partly Cloudy"
          }, {
            "code" : "30",
            "date" : "26 Jun 2017",
            "day" : "Mon",
            "high" : "22",
            "low" : "14",
            "text" : "Partly Cloudy"
          }, {
            "code" : "30",
            "date" : "27 Jun 2017",
            "day" : "Tue",
            "high" : "23",
            "low" : "15",
            "text" : "Partly Cloudy"
          }, {
            "code" : "34",
            "date" : "28 Jun 2017",
            "day" : "Wed",
            "high" : "25",
            "low" : "13",
            "text" : "Mostly Sunny"
          }, {
            "code" : "30",
            "date" : "29 Jun 2017",
            "day" : "Thu",
            "high" : "25",
            "low" : "13",
            "text" : "Partly Cloudy"
          }, {
            "code" : "34",
            "date" : "30 Jun 2017",
            "day" : "Fri",
            "high" : "25",
            "low" : "13",
            "text" : "Mostly Sunny"
          }, {
            "code" : "30",
            "date" : "01 Jul 2017",
            "day" : "Sat",
            "high" : "25",
            "low" : "14",
            "text" : "Partly Cloudy"
          }, {
            "code" : "30",
            "date" : "02 Jul 2017",
            "day" : "Sun",
            "high" : "25",
            "low" : "14",
            "text" : "Partly Cloudy"
          }, {
            "code" : "30",
            "date" : "03 Jul 2017",
            "day" : "Mon",
            "high" : "23",
            "low" : "15",
            "text" : "Partly Cloudy"
          } ],
          "description" : "\n
\nCurrent Conditions:\n
Mostly Cloudy\n
\n
\nForecast:\n
Sat - Mostly Cloudy. High: 25Low: 16\n
Sun - Partly Cloudy. High: 25Low: 15\n
Mon - Partly Cloudy. High: 22Low: 14\n
Tue - Partly Cloudy. High: 23Low: 15\n
Wed - Mostly Sunny. High: 25Low: 13\n
\n
\nFull Forecast at Yahoo! Weather\n
\n
\n(provided by The Weather Channel)\n
\n]]>", "guid" : { "isPermaLink" : "false" } } } } } }

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

Responses

200

Successful operation weatherdata response

Example data

Content-Type: application/json
{query={count=1, created=2017-06-24T23:47:36Z, lang=en-US, results={channel={units={distance=km, pressure=mb, speed=km/h, temperature=C}, title=Yahoo! Weather - Sunnyvale, CA, US, link=http://us.rd.yahoo.com/dailynews/rss/weather/Country__Country/*https://weather.yahoo.com/country/state/city-91990359/, description=Yahoo! Weather for Sunnyvale, CA, US, language=en-us, lastBuildDate=Sat, 24 Jun 2017 04:47 PM PDT, ttl=60, location={city=Sunnyvale, country=United States, region= CA}, wind={chill=73, direction=345, speed=28.97}, atmosphere={humidity=64, pressure=34033.22, rising=0, visibility=25.91}, astronomy={sunrise=5:48 am, sunset=8:33 pm}, image={title=Yahoo! Weather, width=142, height=18, link=http://weather.yahoo.com, url=http://l.yimg.com/a/i/brand/purplelogo//uh/us/news-wea.gif}, item={title=Conditions for Sunnyvale, CA, US at 04:00 PM PDT, lat=37.377499, long=-122.04686, link=http://us.rd.yahoo.com/dailynews/rss/weather/Country__Country/*https://weather.yahoo.com/country/state/city-91990359/, pubDate=Sat, 24 Jun 2017 04:00 PM PDT, condition={code=28, date=Sat, 24 Jun 2017 04:00 PM PDT, temp=22, text=Mostly Cloudy}, forecast=[{code=28, date=24 Jun 2017, day=Sat, high=25, low=16, text=Mostly Cloudy}, {code=30, date=25 Jun 2017, day=Sun, high=25, low=15, text=Partly Cloudy}, {code=30, date=26 Jun 2017, day=Mon, high=22, low=14, text=Partly Cloudy}, {code=30, date=27 Jun 2017, day=Tue, high=23, low=15, text=Partly Cloudy}, {code=34, date=28 Jun 2017, day=Wed, high=25, low=13, text=Mostly Sunny}, {code=30, date=29 Jun 2017, day=Thu, high=25, low=13, text=Partly Cloudy}, {code=34, date=30 Jun 2017, day=Fri, high=25, low=13, text=Mostly Sunny}, {code=30, date=01 Jul 2017, day=Sat, high=25, low=14, text=Partly Cloudy}, {code=30, date=02 Jul 2017, day=Sun, high=25, low=14, text=Partly Cloudy}, {code=30, date=03 Jul 2017, day=Mon, high=23, low=15, text=Partly Cloudy}], description=<![CDATA[<img src="http://l.yimg.com/a/i/us/we/52/28.gif"/>
<BR />
<b>Current Conditions:</b>
<BR />Mostly Cloudy
<BR />
<BR />
<b>Forecast:</b>
<BR /> Sat - Mostly Cloudy. High: 25Low: 16
<BR /> Sun - Partly Cloudy. High: 25Low: 15
<BR /> Mon - Partly Cloudy. High: 22Low: 14
<BR /> Tue - Partly Cloudy. High: 23Low: 15
<BR /> Wed - Mostly Sunny. High: 25Low: 13
<BR />
<BR />
<a href="http://us.rd.yahoo.com/dailynews/rss/weather/Country__Country/*https://weather.yahoo.com/country/state/city-91990359/">Full Forecast at Yahoo! Weather</a>
<BR />
<BR />
(provided by <a href="http://www.weather.com" >The Weather Channel</a>)
<BR />
]]>, guid={isPermaLink=false}}}}}}

WeatherForecast

Up
get /weather
Gets brief details about the weather forecast (getWeather)
Retrieves the weather forecast and summarizes it in one short sentence. Indicates temperature and general conditions for the area.

Query parameters

lat (required)
Query Parameter — latitude coordinates
lng (required)
Query Parameter — longitude coordinates

Return type

weatherResponse

Example data

Content-Type: application/text
"19 c, Mostly Clear at Santa Clara, California"

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

Responses

200

weather response weatherResponse

Example data

Content-Type: application/text
19 c, Mostly Clear at Santa Clara, California

Up

Models

[ Jump to Methods ]

Table of Contents

  1. aqiResponse
  2. astronomy
  3. atmosphere
  4. channel
  5. condition
  6. forecast
  7. forecast array
  8. guid
  9. image
  10. item
  11. location
  12. query
  13. results
  14. units
  15. weatherResponse
  16. weatherdata response
  17. wind

aqiResponse - Up

astronomy - Up

Forecast information about current astronomical conditions
sunrise (optional)
String Today's sunrise time. The time is a string in a local time format of "h:mm am/pm"
sunset (optional)
String Today's sunset time. The time is a string in a local time format of "h:mm am/pm"

atmosphere - Up

Forecast information about current atmospheric pressure, humidity, and visibility
humidity (optional)
Integer humidity, in percent
pressure (optional)
Integer Barometric pressure, in the units specified by the pressure attribute of the yweather:units element ("in" or "mb").
rising (optional)
Integer State of the barometric pressure: steady (0), rising (1), or falling (2).
visibility (optional)
Integer Visibility, in the units specified by the distance attribute of the units element ("mi" or "km"). Note that the visibility is specified as the actual value * 100. For example, a visibility of 16.5 miles will be specified as 1650. A visibility of 14 kilometers will appear as 1400.

channel - Up

units (optional)
title (optional)
String The title of the feed, which includes the location city
link (optional)
String The URL for the Weather page of the forecast for this location
description (optional)
String The overall description of the feed including the location
language (optional)
String The language of the weather forecast
lastBuildDate (optional)
String The last time the feed was updated. The format is in the date format defined by [RFC822 Section 5](http://www.rfc-editor.org/rfc/rfc822.txt).
ttl (optional)
String Time to Live -- how long in minutes this feed should be cached.
location (optional)
wind (optional)
atmosphere (optional)
astronomy (optional)
image (optional)
item (optional)

condition - Up

The current weather conditions
code (optional)
Integer The condition code for this forecast. You could use this code to choose a text description or image for the forecast. The possible values for this element are described in the [Condition Codes](https://developer.yahoo.com/weather/).documentation.html.
date (optional)
String The current date and time for which this forecast applies. The date is in RFC822 Section 5 format.
temp (optional)
Integer The current temperature, in the units specified by the units element.
text (optional)
String A textual description of conditions

forecast - Up

forecast array - Up

The weather forecast for a specific day. The item element contains multiple forecast elements for today and tomorrow.
code (optional)
Integer The condition code for this forecast. You could use this code to choose a text description or image for the forecast. The possible values for this element are described in the [Condition Codes](https://developer.yahoo.com/weather/documentation.html#codes).
date (optional)
String The date to which this forecast applies. The date is in 'dd Mmm yyyy' format, for example '30 Nov 2005'
day (optional)
String Day of the week to which this forecast applies. Possible values are Mon Tue Wed Thu Fri Sat Sun.
high (optional)
Integer The forecasted high temperature for this day, in the units specified by the units element.
low (optional)
Integer The forecasted low temperature for this day, in the units specified by the units element.
text (optional)
String A textual description of conditions

guid - Up

Unique identifier for the forecast, made up of the location ID, the date, and the time.
isPermaLink (optional)
String The attribute isPermaLink is false.

image - Up

The image used to identify this feed
title (optional)
String The title of the image.
width (optional)
String The width of the image, in pixels
height (optional)
String The height of the image, in pixels
link (optional)
String Description of link
url (optional)
String The URL of Yahoo! Weather

item - Up

The item element contains current conditions and forecast for the given location. There are multiple weather forecast elements for today and tomorrow.
title (optional)
String The forecast title and time.
lat (optional)
String The latitude of the location.
long (optional)
String The longitude of the location.
link (optional)
String The Yahoo! Weather URL for this forecast.
pubDate (optional)
String The date and time this forecast was posted, in the date format defined by [RFC822 Section 5](http://www.rfc-editor.org/rfc/rfc822.txt).
condition (optional)
forecast (optional)
description (optional)
String A simple summary of the current conditions and tomorrow's forecast, in HTML format, including a link to Yahoo! Weather for the full forecast.
guid (optional)

location - Up

The location of this forecast
city (optional)
String City name
country (optional)
String Two-character country code
region (optional)
String State, territory, or region, if given

query - Up

count (optional)
Integer The number of items (rows) returned -- specifically, the number of sub-elements in the results property
created (optional)
String The date and time the response was created
lang (optional)
String The locale for the response
results (optional)

results - Up

channel (optional)

units - Up

Units for various aspects of the forecast. Note that the default is to use metric formats for the units (Celsius, kilometers, millibars, kilometers per hour).
distance (optional)
String Units for distance, mi for miles or km for kilometers
pressure (optional)
String Units of barometric pressure, "in" for pounds per square inch or "mb" for millibars.
speed (optional)
String Units of speed, "mph" for miles per hour or "kph" for kilometers per hour.
temperature (optional)
String Degree units, "f" for Fahrenheit or "c" for Celsius.

weatherResponse - Up

weatherdata response - Up

query (optional)

wind - Up

Forecast information about wind
chill (optional)
Integer Wind chill in degrees
direction (optional)
Integer Wind direction, in degrees
speed (optional)
Integer Wind speed, in the units specified in the speed attribute of the units element (mph or kph)