Weather API from Mashape API Reference

This is a sample spec that describes a Mashape Weather API as an example to demonstrate features in the Swagger-2.0 specification. This output is part of the Documenting REST API course on my site. The 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
API Endpoint
https://simple-weather.p.mashape.com
Terms of Service: http://swagger.io/terms/
Contact: [email protected]
Schemes: https
Version: 2.1

Authentication

api_key

name
X-Mashape-Key
in
header

Air Quality

Gets the air quality index

GET /aqi

Air quality is a measure of air pollution. The higher the number, the worse the pollution.

lat

latitude

type
string
in
query
lng

longitude

type
string
in
query
200 OK

AQI response

Response Example (200 OK)
"string"

Weather Forecast

Gets the weather forecast in abbreviated form

GET /weather

retrieves the weather forecast, but without too much detail

lat

latitude coordinates

type
string
in
query
lng

longitude coordinates

type
string
in
query

weather response

Response Example (200 OK)
"string"

Weather Data

Get weather forecast with lots of details

GET /weatherdata

Includes full details of the weather forecast, in JSON format

lat

latitude

type
string
in
query
lng

longitude

type
string
in
query

Successful operation

Response Example (200 OK)
{
  "query": {
    "count": 1,
    "created": "2017-06-14T14:30:14Z",
    "lang": "en-US",
    "results": {
      "channel": {
        "units": {
          "distance": "km",
          "pressure": "mb",
          "speed": "km/h",
          "temperature": "C"
        },
        "title": "Yahoo! Weather - Singapore, South West, SG",
        "link": "http://us.rd.yahoo.com/dailynews/rss/weather/Country__Country/*https://weather.yahoo.com/country/state/city-91792352/",
        "description": "Yahoo! Weather for Singapore, South West, SG",
        "language": "en-us",
        "lastBuildDate": "Wed, 14 Jun 2017 10:30 PM SGT",
        "ttl": "60",
        "location": {
          "city": "Singapore",
          "country": "Singapore",
          "region": "South West"
        },
        "wind": {
          "chill": "81",
          "direction": "158",
          "speed": "11.27"
        },
        "atmosphere": {
          "humidity": "87",
          "pressure": "34168.68",
          "rising": "0",
          "visibility": "25.91"
        },
        "astronomy": {
          "sunrise": "6:59 am",
          "sunset": "7:11 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 Singapore, South West, SG at 09:00 PM SGT",
          "lat": "1.33464",
          "long": "103.726471",
          "link": "http://us.rd.yahoo.com/dailynews/rss/weather/Country__Country/*https://weather.yahoo.com/country/state/city-91792352/",
          "pubDate": "Wed, 14 Jun 2017 09:00 PM SGT",
          "condition": {
            "code": "33",
            "date": "Wed, 14 Jun 2017 09:00 PM SGT",
            "temp": "26",
            "text": "Mostly Clear"
          },
          "forecast": [
            {
              "code": "4",
              "date": "14 Jun 2017",
              "day": "Wed",
              "high": "28",
              "low": "25",
              "text": "Thunderstorms"
            }
          ],
          "description": "<![CDATA[<img src=\"http://l.yimg.com/a/i/us/we/52/4.gif\"/>\n<BR />\n<b>Current Conditions:</b>\n<BR />Thunderstorms\n<BR />\n<BR />\n<b>Forecast:</b>\n<BR /> Fri - Thunderstorms. High: 30Low: 25\n<BR /> Sat - Thunderstorms. High: 28Low: 25\n<BR /> Sun - Thunderstorms. High: 28Low: 25\n<BR /> Mon - Thunderstorms. High: 28Low: 25\n<BR /> Tue - Thunderstorms. High: 28Low: 25\n<BR />\n<BR />\n<a href=\"http://us.rd.yahoo.com/dailynews/rss/weather/Country__Country/*https://weather.yahoo.com/country/state/city-91792352/\">Full Forecast at Yahoo! Weather</a>\n<BR />\n<BR />\n(provided by <a href=\"http://www.weather.com\" >The Weather Channel</a>)\n<BR />\n]]>",
          "guid": {
            "isPermaLink": "false"
          }
        }
      }
    }
  }
}

Schema Definitions

aqiResponse: string

Example
"string"

weatherResponse: string

Example
"string"

weatherdata response: object

query: query
Example
{
  "query": {
    "count": 1,
    "created": "2017-06-14T14:30:14Z",
    "lang": "en-US",
    "results": {
      "channel": {
        "units": {
          "distance": "km",
          "pressure": "mb",
          "speed": "km/h",
          "temperature": "C"
        },
        "title": "Yahoo! Weather - Singapore, South West, SG",
        "link": "http://us.rd.yahoo.com/dailynews/rss/weather/Country__Country/*https://weather.yahoo.com/country/state/city-91792352/",
        "description": "Yahoo! Weather for Singapore, South West, SG",
        "language": "en-us",
        "lastBuildDate": "Wed, 14 Jun 2017 10:30 PM SGT",
        "ttl": "60",
        "location": {
          "city": "Singapore",
          "country": "Singapore",
          "region": "South West"
        },
        "wind": {
          "chill": "81",
          "direction": "158",
          "speed": "11.27"
        },
        "atmosphere": {
          "humidity": "87",
          "pressure": "34168.68",
          "rising": "0",
          "visibility": "25.91"
        },
        "astronomy": {
          "sunrise": "6:59 am",
          "sunset": "7:11 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 Singapore, South West, SG at 09:00 PM SGT",
          "lat": "1.33464",
          "long": "103.726471",
          "link": "http://us.rd.yahoo.com/dailynews/rss/weather/Country__Country/*https://weather.yahoo.com/country/state/city-91792352/",
          "pubDate": "Wed, 14 Jun 2017 09:00 PM SGT",
          "condition": {
            "code": "33",
            "date": "Wed, 14 Jun 2017 09:00 PM SGT",
            "temp": "26",
            "text": "Mostly Clear"
          },
          "forecast": [
            {
              "code": "4",
              "date": "14 Jun 2017",
              "day": "Wed",
              "high": "28",
              "low": "25",
              "text": "Thunderstorms"
            }
          ],
          "description": "<![CDATA[<img src=\"http://l.yimg.com/a/i/us/we/52/4.gif\"/>\n<BR />\n<b>Current Conditions:</b>\n<BR />Thunderstorms\n<BR />\n<BR />\n<b>Forecast:</b>\n<BR /> Fri - Thunderstorms. High: 30Low: 25\n<BR /> Sat - Thunderstorms. High: 28Low: 25\n<BR /> Sun - Thunderstorms. High: 28Low: 25\n<BR /> Mon - Thunderstorms. High: 28Low: 25\n<BR /> Tue - Thunderstorms. High: 28Low: 25\n<BR />\n<BR />\n<a href=\"http://us.rd.yahoo.com/dailynews/rss/weather/Country__Country/*https://weather.yahoo.com/country/state/city-91792352/\">Full Forecast at Yahoo! Weather</a>\n<BR />\n<BR />\n(provided by <a href=\"http://www.weather.com\" >The Weather Channel</a>)\n<BR />\n]]>",
          "guid": {
            "isPermaLink": "false"
          }
        }
      }
    }
  }
}

query: object

count: integer

The number of items (rows) returned -- specifically, the number of sub-elements in the results property

created: string

The date and time the response was created

lang: string

The locale for the response

results: results
Example
{
  "count": 1,
  "created": "2017-06-14T14:30:14Z",
  "lang": "en-US",
  "results": {
    "channel": {
      "units": {
        "distance": "km",
        "pressure": "mb",
        "speed": "km/h",
        "temperature": "C"
      },
      "title": "Yahoo! Weather - Singapore, South West, SG",
      "link": "http://us.rd.yahoo.com/dailynews/rss/weather/Country__Country/*https://weather.yahoo.com/country/state/city-91792352/",
      "description": "Yahoo! Weather for Singapore, South West, SG",
      "language": "en-us",
      "lastBuildDate": "Wed, 14 Jun 2017 10:30 PM SGT",
      "ttl": "60",
      "location": {
        "city": "Singapore",
        "country": "Singapore",
        "region": "South West"
      },
      "wind": {
        "chill": "81",
        "direction": "158",
        "speed": "11.27"
      },
      "atmosphere": {
        "humidity": "87",
        "pressure": "34168.68",
        "rising": "0",
        "visibility": "25.91"
      },
      "astronomy": {
        "sunrise": "6:59 am",
        "sunset": "7:11 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 Singapore, South West, SG at 09:00 PM SGT",
        "lat": "1.33464",
        "long": "103.726471",
        "link": "http://us.rd.yahoo.com/dailynews/rss/weather/Country__Country/*https://weather.yahoo.com/country/state/city-91792352/",
        "pubDate": "Wed, 14 Jun 2017 09:00 PM SGT",
        "condition": {
          "code": "33",
          "date": "Wed, 14 Jun 2017 09:00 PM SGT",
          "temp": "26",
          "text": "Mostly Clear"
        },
        "forecast": [
          {
            "code": "4",
            "date": "14 Jun 2017",
            "day": "Wed",
            "high": "28",
            "low": "25",
            "text": "Thunderstorms"
          }
        ],
        "description": "<![CDATA[<img src=\"http://l.yimg.com/a/i/us/we/52/4.gif\"/>\n<BR />\n<b>Current Conditions:</b>\n<BR />Thunderstorms\n<BR />\n<BR />\n<b>Forecast:</b>\n<BR /> Fri - Thunderstorms. High: 30Low: 25\n<BR /> Sat - Thunderstorms. High: 28Low: 25\n<BR /> Sun - Thunderstorms. High: 28Low: 25\n<BR /> Mon - Thunderstorms. High: 28Low: 25\n<BR /> Tue - Thunderstorms. High: 28Low: 25\n<BR />\n<BR />\n<a href=\"http://us.rd.yahoo.com/dailynews/rss/weather/Country__Country/*https://weather.yahoo.com/country/state/city-91792352/\">Full Forecast at Yahoo! Weather</a>\n<BR />\n<BR />\n(provided by <a href=\"http://www.weather.com\" >The Weather Channel</a>)\n<BR />\n]]>",
        "guid": {
          "isPermaLink": "false"
        }
      }
    }
  }
}

results: object

channel: channel
Example
{
  "channel": {
    "units": {
      "distance": "km",
      "pressure": "mb",
      "speed": "km/h",
      "temperature": "C"
    },
    "title": "Yahoo! Weather - Singapore, South West, SG",
    "link": "http://us.rd.yahoo.com/dailynews/rss/weather/Country__Country/*https://weather.yahoo.com/country/state/city-91792352/",
    "description": "Yahoo! Weather for Singapore, South West, SG",
    "language": "en-us",
    "lastBuildDate": "Wed, 14 Jun 2017 10:30 PM SGT",
    "ttl": "60",
    "location": {
      "city": "Singapore",
      "country": "Singapore",
      "region": "South West"
    },
    "wind": {
      "chill": "81",
      "direction": "158",
      "speed": "11.27"
    },
    "atmosphere": {
      "humidity": "87",
      "pressure": "34168.68",
      "rising": "0",
      "visibility": "25.91"
    },
    "astronomy": {
      "sunrise": "6:59 am",
      "sunset": "7:11 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 Singapore, South West, SG at 09:00 PM SGT",
      "lat": "1.33464",
      "long": "103.726471",
      "link": "http://us.rd.yahoo.com/dailynews/rss/weather/Country__Country/*https://weather.yahoo.com/country/state/city-91792352/",
      "pubDate": "Wed, 14 Jun 2017 09:00 PM SGT",
      "condition": {
        "code": "33",
        "date": "Wed, 14 Jun 2017 09:00 PM SGT",
        "temp": "26",
        "text": "Mostly Clear"
      },
      "forecast": [
        {
          "code": "4",
          "date": "14 Jun 2017",
          "day": "Wed",
          "high": "28",
          "low": "25",
          "text": "Thunderstorms"
        }
      ],
      "description": "<![CDATA[<img src=\"http://l.yimg.com/a/i/us/we/52/4.gif\"/>\n<BR />\n<b>Current Conditions:</b>\n<BR />Thunderstorms\n<BR />\n<BR />\n<b>Forecast:</b>\n<BR /> Fri - Thunderstorms. High: 30Low: 25\n<BR /> Sat - Thunderstorms. High: 28Low: 25\n<BR /> Sun - Thunderstorms. High: 28Low: 25\n<BR /> Mon - Thunderstorms. High: 28Low: 25\n<BR /> Tue - Thunderstorms. High: 28Low: 25\n<BR />\n<BR />\n<a href=\"http://us.rd.yahoo.com/dailynews/rss/weather/Country__Country/*https://weather.yahoo.com/country/state/city-91792352/\">Full Forecast at Yahoo! Weather</a>\n<BR />\n<BR />\n(provided by <a href=\"http://www.weather.com\" >The Weather Channel</a>)\n<BR />\n]]>",
      "guid": {
        "isPermaLink": "false"
      }
    }
  }
}

channel: object

units: units
title: string

The title of the feed, which includes the location city

link: string

The URL for the Weather page of the forecast for this location

description: string

The overall description of the feed including the location

language: string

The language of the weather forecast

lastBuildDate: string

The last time the feed was updated. The format is in the date format defined by RFC822 Section 5.

ttl: string

Time to Live -- how long in minutes this feed should be cached.

location: location
wind: wind
atmosphere: atmosphere
astronomy: astronomy
image: image
item: item
Example
{
  "units": {
    "distance": "km",
    "pressure": "mb",
    "speed": "km/h",
    "temperature": "C"
  },
  "title": "Yahoo! Weather - Singapore, South West, SG",
  "link": "http://us.rd.yahoo.com/dailynews/rss/weather/Country__Country/*https://weather.yahoo.com/country/state/city-91792352/",
  "description": "Yahoo! Weather for Singapore, South West, SG",
  "language": "en-us",
  "lastBuildDate": "Wed, 14 Jun 2017 10:30 PM SGT",
  "ttl": "60",
  "location": {
    "city": "Singapore",
    "country": "Singapore",
    "region": "South West"
  },
  "wind": {
    "chill": "81",
    "direction": "158",
    "speed": "11.27"
  },
  "atmosphere": {
    "humidity": "87",
    "pressure": "34168.68",
    "rising": "0",
    "visibility": "25.91"
  },
  "astronomy": {
    "sunrise": "6:59 am",
    "sunset": "7:11 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 Singapore, South West, SG at 09:00 PM SGT",
    "lat": "1.33464",
    "long": "103.726471",
    "link": "http://us.rd.yahoo.com/dailynews/rss/weather/Country__Country/*https://weather.yahoo.com/country/state/city-91792352/",
    "pubDate": "Wed, 14 Jun 2017 09:00 PM SGT",
    "condition": {
      "code": "33",
      "date": "Wed, 14 Jun 2017 09:00 PM SGT",
      "temp": "26",
      "text": "Mostly Clear"
    },
    "forecast": [
      {
        "code": "4",
        "date": "14 Jun 2017",
        "day": "Wed",
        "high": "28",
        "low": "25",
        "text": "Thunderstorms"
      }
    ],
    "description": "<![CDATA[<img src=\"http://l.yimg.com/a/i/us/we/52/4.gif\"/>\n<BR />\n<b>Current Conditions:</b>\n<BR />Thunderstorms\n<BR />\n<BR />\n<b>Forecast:</b>\n<BR /> Fri - Thunderstorms. High: 30Low: 25\n<BR /> Sat - Thunderstorms. High: 28Low: 25\n<BR /> Sun - Thunderstorms. High: 28Low: 25\n<BR /> Mon - Thunderstorms. High: 28Low: 25\n<BR /> Tue - Thunderstorms. High: 28Low: 25\n<BR />\n<BR />\n<a href=\"http://us.rd.yahoo.com/dailynews/rss/weather/Country__Country/*https://weather.yahoo.com/country/state/city-91792352/\">Full Forecast at Yahoo! Weather</a>\n<BR />\n<BR />\n(provided by <a href=\"http://www.weather.com\" >The Weather Channel</a>)\n<BR />\n]]>",
    "guid": {
      "isPermaLink": "false"
    }
  }
}

units: object

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: string

Units for distance, mi for miles or km for kilometers

pressure: string

Units of barometric pressure, "in" for pounds per square inch or "mb" for millibars.

speed: string

Units of speed, "mph" for miles per hour or "kph" for kilometers per hour.

temperature: string

Degree units, "f" for Fahrenheit or "c" for Celsius.

Example
{
  "distance": "km",
  "pressure": "mb",
  "speed": "km/h",
  "temperature": "C"
}

location: object

The location of this forecast

city: string

City name

country: string

Two-character country code

region: string

State, territory, or region, if given

Example
{
  "city": "Singapore",
  "country": "Singapore",
  "region": "South West"
}

wind: object

Forecast information about wind

chill: integer

Wind chill in degrees

direction: integer

Wind direction, in degrees

speed: integer

Wind speed, in the units specified in the speed attribute of the units element (mph or kph)

Example
{
  "chill": "81",
  "direction": "158",
  "speed": "11.27"
}

atmosphere: object

Forecast information about current atmospheric pressure, humidity, and visibility

humidity: integer

humidity, in percent

pressure: integer

Barometric pressure, in the units specified by the pressure attribute of the yweather:units element ("in" or "mb").

rising: integer

State of the barometric pressure: steady (0), rising (1), or falling (2).

visibility: 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.

Example
{
  "humidity": "87",
  "pressure": "34168.68",
  "rising": "0",
  "visibility": "25.91"
}

astronomy: object

Forecast information about current astronomical conditions

sunrise: string

Today's sunrise time. The time is a string in a local time format of "h:mm am/pm"

sunset: string

Today's sunset time. The time is a string in a local time format of "h:mm am/pm"

Example
{
  "sunrise": "6:59 am",
  "sunset": "7:11 pm"
}

image: object

The image used to identify this feed

title: string

The title of the image.

width: string

The width of the image, in pixels

height: string

The height of the image, in pixels

link: string

Description of link

url: string

The URL of Yahoo! Weather

Example
{
  "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: object

The item element contains current conditions and forecast for the given location. There are multiple weather forecast elements for today and tomorrow.

title: string

The forecast title and time.

lat: string

The latitude of the location.

long: string

The longitude of the location.

link: string

The Yahoo! Weather URL for this forecast.

pubDate: string

The date and time this forecast was posted, in the date format defined by RFC822 Section 5.

condition: condition
forecast: forecast
description: 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: guid
Example
{
  "title": "Conditions for Singapore, South West, SG at 09:00 PM SGT",
  "lat": "1.33464",
  "long": "103.726471",
  "link": "http://us.rd.yahoo.com/dailynews/rss/weather/Country__Country/*https://weather.yahoo.com/country/state/city-91792352/",
  "pubDate": "Wed, 14 Jun 2017 09:00 PM SGT",
  "condition": {
    "code": "33",
    "date": "Wed, 14 Jun 2017 09:00 PM SGT",
    "temp": "26",
    "text": "Mostly Clear"
  },
  "forecast": [
    {
      "code": "4",
      "date": "14 Jun 2017",
      "day": "Wed",
      "high": "28",
      "low": "25",
      "text": "Thunderstorms"
    }
  ],
  "description": "<![CDATA[<img src=\"http://l.yimg.com/a/i/us/we/52/4.gif\"/>\n<BR />\n<b>Current Conditions:</b>\n<BR />Thunderstorms\n<BR />\n<BR />\n<b>Forecast:</b>\n<BR /> Fri - Thunderstorms. High: 30Low: 25\n<BR /> Sat - Thunderstorms. High: 28Low: 25\n<BR /> Sun - Thunderstorms. High: 28Low: 25\n<BR /> Mon - Thunderstorms. High: 28Low: 25\n<BR /> Tue - Thunderstorms. High: 28Low: 25\n<BR />\n<BR />\n<a href=\"http://us.rd.yahoo.com/dailynews/rss/weather/Country__Country/*https://weather.yahoo.com/country/state/city-91792352/\">Full Forecast at Yahoo! Weather</a>\n<BR />\n<BR />\n(provided by <a href=\"http://www.weather.com\" >The Weather Channel</a>)\n<BR />\n]]>",
  "guid": {
    "isPermaLink": "false"
  }
}

condition: object

The current weather conditions

code: 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.documentation.html.

date: string

The current date and time for which this forecast applies. The date is in RFC822 Section 5 format.

temp: integer

The current temperature, in the units specified by the units element.

text: string

A textual description of conditions

Example
{
  "code": "33",
  "date": "Wed, 14 Jun 2017 09:00 PM SGT",
  "temp": "26",
  "text": "Mostly Clear"
}

forecast: object[]

Example
[
  {
    "code": "4",
    "date": "14 Jun 2017",
    "day": "Wed",
    "high": "28",
    "low": "25",
    "text": "Thunderstorms"
  }
]

forecast array: object

The weather forecast for a specific day. The item element contains multiple forecast elements for today and tomorrow.

code: 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.

date: string

The date to which this forecast applies. The date is in 'dd Mmm yyyy' format, for example '30 Nov 2005'

day: string

Day of the week to which this forecast applies. Possible values are Mon Tue Wed Thu Fri Sat Sun.

high: integer

The forecasted high temperature for this day, in the units specified by the units element.

low: integer

The forecasted low temperature for this day, in the units specified by the units element.

text: string

A textual description of conditions

Example
{
  "code": "4",
  "date": "14 Jun 2017",
  "day": "Wed",
  "high": "28",
  "low": "25",
  "text": "Thunderstorms"
}

guid: object

Unique identifier for the forecast, made up of the location ID, the date, and the time.

isPermaLink: string

The attribute isPermaLink is false.

Example
{
  "isPermaLink": "false"
}