URL | Parameters | Response Properties | Examples | Query1 | Response1 | Query2 | Response2

The weather method takes any valid entity's guid and returns the current, real time, weather conditions for that entity's location in the continental United States (and soon, most of the world). You can find specific conditions for a point entity, or average conditions across a boundary-defined entity such as a city. For boundary entities, weather interpolates conditions between weather stations rather than just return information from the closest station.

weather uses the WeatherBug backend for its data. Thus, you must abide by the WeatherBug API Terms of Use if your application uses this method.

Results are a JSON array of properties and their numerical values, save for one string timestamp value. By default, values are in imperial/English units such as Fahrenheit degrees and inches. You can use a request parameter to change all units to metric.

An invalid guid argument results in a HTTP 404 error response. If the weather service is down, or weather data is not available for the area, all results have null values. If there is a problem with our servers, you may get the response {"error": "you've encountered an internal error :-( please contact api@townme.com if it persists"}

URL          [Top]

http://api.geoapi.com/v1/e/<guid>/view/weather

http://api.geoapi.com/v1/e/<guid>/view/weather:units=metric

Parameters          [Top]

• guid:
  • Required.
  • Any valid entity's guid.
  • Format: String.
• units:
  • Optional.
  • Specifies whether results are given in imperial (English) or metric units. By default, results are in imperial units. Use metric to change to metric units, You can also use imperial to make it clear that you want to return values in imperial units.
  • Format: String. Unlike other parameters, you append units to the method name with a colon, with its argument value appended to it after an equal sign. For example, .../weather:units=metric 

• apikey:
  • Required.
  • Your application's GeoAPI key.
  • Format: String.
• pretty:
  • Optional.
  • Enables easier to read prettified JSON in result.
  • Format: Set equal to 1 to enable prettification.
• jsoncallback:
  • Optional.
  • Return response in JSONP format. JQuery has nice support for JSONP callbacks.
  • Format: JSON prefix string.

Response Properties          [Top]

All values are floating point numbers, unless otherwise specified.  Temperatures may be positive or negative numbers. Value units depend on the category, and default to imperial (English) units unless you append the :units=metric parameter to the weather view name in the request. null is returned for any unavailable value.

For point entities, values are interpolated based on geography and nearby weather stations. For region entities, like a neighborhood or city, most values are a numerical average over the region. However, since radar data is typically spotty, for radar values the maximum value is returned.

WARNING: We may add more weather properties later on. When processing weather method response data, make sure your code safely ignores any unknown to it properties and their values.

• DailyRain: Amount of rain in inches for the current day 24 hour period Metric units are millimeters.
• Humidity: Humidity expressed as a percentage.

• Pressure: Air pressure (barometer reading) in inches of mercury. Metric units are millibars.

• Radar: An integer that's the sum of  the type of precipitation (100 = rain, 200 = sleet, 400=snow) and its intensity (from 5 to 75). A null value means there is no radar-visible precipitation.  For a region, the max value of any point in the region is returned. Updated about every 5 minutes.
• Temperature: Current surface temperature in degrees Fahrenheit. Metric units are degrees Celsius.
• WindChill: Apparent temperature in Fahrenheit If there is a wind chill effect. If there is no wind chill effect, the value is null.  Metric units are degrees Celsius.
• HeatIndex: Apparent temperature in Fahrenheit if there is a heat index (due to humidity). If there is no heat index effect, the value is null. Metric units are degrees Celsius.
• DewPoint: Surface temperature in Fahrenheit at which current conditions will cause water vapor to condense into water (dew).  Metric units are degrees Celsius.
• WindSpeed: Current wind speed in miles per hour.  Metric units are kilometers per hour.
• UpdateTime: UTC time of most recent data acquisition.  The format is an ISO8601 time string, such as "2009-12-04T02:16:01Z"

Examples          [Top]

Query1          [Top]

http://api.geoapi.com/v1/e/san-francisco-zoo-san-francisco-ca/view/weather?apikey=demo&pretty=1

Response1          [Top]

{
"query": {
"type": "entity-view", 
"params": {
"guid": "san-francisco-zoo-san-francisco-ca", 
"view": "weather"
}
}, 
"result": [
{
"UpdateTime": "2009-12-04T03:00:24Z", 
"DailyRain": 0, 
"Temperature": 47, 
"DewPoint": 39, 
"Radar": 0, 
"HeatIndex": null, 
"Humidity": 82.8, 
"Pressure": 30.2, 
"WindSpeed": 2, 
"WindChill": null
}
]
}

Query2          [Top]

http://api.geoapi.com/v1/e/san-francisco-ca/view/weather?apikey=demo&pretty=1

Response2          [Top]

{
"query": {
"type": "entity-view", 
"params": {
"guid": "san-francisco-ca", 
"view": "weather:units=metric"
}
}, 
"result": [
{
"UpdateTime": "2009-12-04T03:00:24Z", 
"DailyRain": 0, 
"Temperature": 8.3, 
"DewPoint": 3.9, 
"Radar": 0, 
"HeatIndex": null, 
"Humidity": 81.7, 
"Pressure": 1022.3, 
"WindSpeed": 1.2, 
"WindChill": null
}
]
}