the weather channel® api implementation guide...the weather channel® api implementation guide the...
TRANSCRIPT
TWC Confidential Page 1 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
The Weather Channel® API
Implementation Guide
Version 1.01
TWC Confidential Page 2 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
Table of Contents
1. EXECUTIVE OVERVIEW .................................................................................................... 4
1.1. Introduction ....................................................................................................................... 4
1.1.1. The Service includes ................................................................................................ 4 1.1.2. Payment Terms ........................................................................................................ 6 1.1.3. Privacy .................................................................................................................... 6 1.1.4. Service Limitations .................................................................................................. 7
Authorized Application / Authorized Website Audience Size ...................................7
Metering ...................................................................................................................8 Caching ....................................................................................................................8 Technology Platforms ..............................................................................................8 Sharing API Keys .....................................................................................................9
1.1.5. The Weather Channel API Implementation Guide .................................................. 9
1.2. Security ............................................................................................................................. 9
1.2.1. Security - API Keys ............................................................................................... 10 1.3. Supported Languages and Locales ................................................................................. 10
2. Implementation ..................................................................................................................... 11
2.1. URLs ............................................................................................................................... 11 2.1.1. The Image Service ................................................................................................. 12
2.2. CallBack Parameters ....................................................................................................... 14
2.3. General Command Overview ......................................................................................... 15 2.4. Daily Data Forecast ........................................................................................................ 17
2.4.1. Sample URLs (Daily Data Forecast) ..................................................................... 17 2.4.2. Parameters ............................................................................................................. 18 2.4.3. Data Nodes (Daily Data Forecast) ........................................................................ 18
2.4.4. Sample results (Daily Data Forecast) .................................................................... 19
2.5. Narrative Forecast ........................................................................................................... 19 2.5.1. Sample URLs (Narrative Forecast) ....................................................................... 20 2.5.2. Parameters (Narrative Forecast) ............................................................................ 20
2.5.3. Data Nodes (Narrative Forecast) ........................................................................... 20 2.5.4. Sample results (Narrative Forecast) ...................................................................... 20
2.6. Abbreviated U.S. Severe Weather Alerts ....................................................................... 21 2.6.1. Sample URLs (Abbreviated U.S. Severe Weather Alerts) .................................... 21 2.6.2. Data Nodes (Abbreviated U.S. Severe Weather Alerts) ....................................... 21
2.6.3. Sample results (Abbreviated U.S. Severe Weather Alerts) ................................... 22 2.7. TruPoint Current Conditions .......................................................................................... 22
2.7.1. Sample URLs (TruPoint Current Conditions) ....................................................... 22
2.7.2. Data Nodes (TruPoint Current Conditions) .......................................................... 23 2.7.3. Sample results (TruPoint Current Conditions) ...................................................... 23
2.8. Locations ......................................................................................................................... 24 2.8.1. Sample URLs (Locations) ..................................................................................... 24 2.8.1.1. Countries with Overlapping Zip Codes / Postal Codes .................................... 24 2.8.2. Data Nodes (Locations) ......................................................................................... 24 2.8.3. Sample results (Locations) .................................................................................... 25
2.10. Location Search.......................................................................................................... 25
TWC Confidential Page 3 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
2.10.1. Sample URLs (Location Search) ........................................................................... 25 2.10.2. Data Nodes (Location) .......................................................................................... 26 2.10.3. Sample results (Location Search) .......................................................................... 26
2.11. Sunrise/Sunset ............................................................................................................ 27
2.11.1. Sample URLs (Sunrise/Sunset) ............................................................................. 27 2.11.2. Parameters (Type Sunrise/Sunset) ........................................................................ 27 2.11.3. Data Nodes (Sunrise/Sunset) ................................................................................. 28 2.11.4. Sample results (Sunrise/Sunset) ............................................................................ 28
2.12. Climatology (Monthly Averages) ............................................................................. 28
2.12.1. Sample URLs (Averages/Record) ......................................................................... 29 2.12.2. Parameters (Climatology (Averages/Records)) .................................................... 29 2.12.3. Data Nodes (Climatology (Averages/Records)) ................................................... 29 2.12.4. Sample results (Climatology (Monthly Averages)) .............................................. 30
2.13. The Weather Channel API Image Service ................................................................. 30
2.13.1. Map Imagery available for the United States of America ..................................... 30
2.13.2. Sample URLs (U.S. National Maps) ..................................................................... 32 2.13.3. Sample URLs (U.S. Regional Maps) .................................................................... 33
TWC Confidential Page 4 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
1. EXECUTIVE OVERVIEW
1.1. Introduction
The Weather Channel® API is an unbranded (i.e. white label), electronic information service
containing meteorological information (the “Service”) that is being made available under a
subscription model by TWC in either XML or JSON data formats. Map imagery is also
available in jpeg format and sky condition iconography is available in png format. The TWC
iconography name is mapped to the sky condition icon value returned in the Service for TruPoint
Current Conditions and 3-Day and 5-Day Data and Narrative (Text) forecasts. While we have
made these icons available to you to help simplify your presentation of weather data, you are not
required to use the TWC icon set.
The Service is intended for use in commercial applications and leverages a world class cloud-
based infrastructure. The Service is currently available for subscription in 33 countries and has
built-in support in the TruPoint Current Conditions, 3-Day Data, and 5-Day Data forecast
modules for multiple languages including English, Spanish, French, German, and Portuguese.
Please use the “Check Availability” tool on the Service‟s website
(http://portal.theweatherchannel.com) to ensure subscription availability in your country.
Prior to subscribing, you may evaluate the Service for FREE by completing the basic
registration associated with The Weather Channel API and then signing in to the “Can I try it
before I subscribe?” feature of The Weather Channel portal, known as The Weather Channel API
Console. The Weather Channel API Console has been designed to allow you to review all
features and functions associated with a subscription to the Service (other than map imagery
which will not be accessible through the API Console until early Q1/2012) so that you can make
an informed decision before subscribing. You may also use The Weather Channel API Console
as a “debugging sandbox” after you subscribe. Data requests made through The Weather
Channel API Console use a special “Magic Key” associated with your registration and do not
impact the data requests that are associated with a subscription plan. There is a daily limit of 100
data requests per registered user per day. This limit is reset each day at midnight UTC.
1.1.1. The Service includes
access to weather information for over 100,000 worldwide location IDs;
a location search function that may be used to translate a worldwide city name such as
“Atlanta” into a TWC proprietary location ID (“LocID”) such as “USGA0028” prior to
making a request for weather information (note: all U.S. zip codes and all U.K., French,
and German postal codes are already valid LocIDs and do not require a search);
location specific information that you may want for data presentation including the name
of the city, state/province, country, the zip / postal code, and the time zone offset;
current conditions information (i.e. the sky condition, temperature, "feels like"
temperature, wind speed and direction, wind gusts, barometric pressure & barometric
trend, humidity, visibility, U.V. index, and dew point) for a selected location;
TWC Confidential Page 5 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
abbreviated U.S. severe weather alerts for a selected location ID, if that location is within
the continental United States of America and the National Weather Service has issued an
alert for the county in which the location resides. Abbreviated U.S. severe weather alert
information includes such information as a headline (by way of example: “Flash Flood
Watch in effect from 6PM MDT TUE until NOON MDT WED”), the name of the county
affected, the severity level, and the start and end time of the alert;
up to five (5) days of forecast information (i.e. the sky condition, high / low temperature,
wind speed and direction, humidity, chance of precipitation, and U.V. index) are
available in a data format in any of 5 available languages -- English, Spanish, French,
German, or Portuguese. You also have the option of getting the forecast in narrative
(text) format (by way of example: Thunderstorms during the morning hours, then skies
turning partly cloudy during the afternoon. High 59F. Winds ENE at 5 to 10 mph.).
Currently this narrative option is only available in the English language;
sunrise/sunset information;
climatology data/monthly averages (in the continental United States of America, data will
include monthly average high and low temperature, mean temperature, average
precipitation, record high and low temperature and the date associated with the record for
a selected location; outside of the continental U.S., the data will include the monthly
average high and low temperature for a selected location and may include mean
temperature and average precipitation if such data is available to TWC for that LocID);
and
map imagery associated with the United States of America
o U.S. National Maps
Today‟s Forecasted High Temperatures & Weather Conditions for select
cities across the continental U.S.;
Tonight‟s Forecasted Low Temperatures & Weather Conditions for select
cities across the continental U.S.;
National Precipitation Forecast Map for the continental U.S.; and
National Doppler Radar Map for the continental U.S.
o U.S. Regional Maps
Today‟s Forecasted High Temperatures for select cities within each of the
nine (9) regions TWC has defined in the continental U.S.;
Tonight‟s Forecasted Lows for select cities within each of the nine (9)
regions TWC has defined in the continental U.S.;
Regional Precipitation Forecast Map for each of the nine (9) regions TWC
has defined in the continental U.S.;
Regional Doppler Radar Maps for each of the nine (9) regions TWC has
defined in the continental U.S. (each map will display an area of
approximately 1,800 miles);
Alaska Radar Map – a Doppler Radar map covering an area of
approximately 2,100 miles that includes the State of Alaska;
Hawaii Radar Map – a Doppler Radar map covering an area of
approximately 600 miles that includes the State of Hawaii; and
Puerto Rico / U.S. Virgin Islands Radar Map – a Doppler Radar map
covering an area of approximately 600 miles that includes Puerto Rico and
the United States Virgin Islands.
TWC Confidential Page 6 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
1.1.2. Payment Terms
Subscriptions to the Service are either monthly or yearly. Both are recurring. This means that
you will authorize your credit card to be automatically charged each month or each year on the
anniversary date of your subscription for continued access to the Service. You may cancel at any
time by calling TWC at 770-226-2329 (“The Weather Channel API Hotline”) during normal
business hours or notifying TWC via the “Notify TWC of my intent not to renew my
subscription” option in the My Account section of The Weather Channel API portal, 24-hours
per day. If you submit an electronic request, a TWC business representative will call you within
one (1) business day to verify the validity of the request. Once the validity has been verified, the
subscription will be set to “non-renewal”. You may continue to use the subscription through the
last day of the current subscription period. There are no prorated refunds offered on monthly
subscriptions. If you selected an annual subscription and you change your mind in the 1st 30
days, TWC will refund you the difference between the annual subscription price and a single
month subscription at the non-discounted monthly rate for the equivalent functionality and
quantity of data requests (all annual subscriptions receive a 8.33% prepaid discount – the
equivalent of getting one month free).
TWC currently only accepts VISA and MasterCard credit cards for subscription payments and
all subscription payments are in U.S. dollars. The Service currently supports having a single
credit card / billing address associated with an account regardless of the number of subscriptions
associated with that account. In the future, TWC plans to allow each subscription to have its
own credit card / billing address so that subscribers can spread their subscription fees across
multiple cards to manage their cash flow and rewards points. It is important to note that in order
for TWC to comply with the various tax jurisdictions around the world, the address associated
with your business contact information (i.e. your physical presence location) or your personal
contact information for non-business, individual subscribers (i.e. your country of residence) is set
as the controlling geography for taxation. As such you must use a credit card with a billing
address in the same country as the address in your contact information. Should you be located in
the United States, you must use a credit card with a billing address in the same state as the
address in your contact information. And if by chance you are located in Frisco, Texas, your
credit card billing address must also be located in Frisco, Texas.
1.1.3. Privacy
The Service, including registration, billing, and payment processing, is housed on servers
operated in the United States. If you are located in the European Union, Canada, or elsewhere
outside of the United States, please be aware that information we collect will be transferred to,
and processed and stored in the United States, a jurisdiction in which the privacy laws may not
be as comprehensive as those in the country where you reside or are a citizen. To become a
subscriber, you must unambiguously consent to the TWC Privacy Policy and to the collection,
transfer, storage, and processing of such information in the United States.
TWC Confidential Page 7 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
1.1.4. Service Limitations
The Weather Channel API has been designed for use by the small to medium size business
(“SMB”) market. As such, TWC has established certain limitations on the use of the Service.
Below is a brief outline of some of the limitations associated with the Service. Your Designated
Application must comply with these limitations in order to use the Service. The list below is not
comprehensive. Please carefully review the End User Agreement associated with a subscription
to the Service before processing your payment. To ensure reasonable attention is paid to this
matter, TWC requires that you read through the End User Agreement to the end and then
manually enter in the name of Your Designated Application. You must then click an
“Authorize” button to acknowledge that this is the only application or website being authorized
for use with the Service. You must then check a box indicating that you have read and agree to
all of the terms of the End User Agreement and then you must manually enter your registration
password as a form of “electronic signature”. For your convenience, TWC provides a link to
print out the End User Agreement to review in printed form before subscribing.
If you have any questions, please contact TWC business representatives before subscribing via e-
mail at [email protected] or call TWC at (770) 226-2329 between the hours
of 9:30 am and 6:30 pm ET, excluding holidays, and select option 8.
Authorized Application / Authorized Website Audience Size
Unique Audience and Pageviews:
When Your Designated Application is a downloadable personal computer application
including, by way of example, widgets, gadgets, toolbars and browser extensions, or a
downloadable mobile phone application, or a mobile smart phone application, Your
Designated Application cannot exceed a monthly unique audience of one hundred and
twenty five thousand (125,000). For clarity, this audience metric is not associated with
downloads. It is associated with active unique monthly users of Your Designated
Application; and
When Your Designated Application is a world wide web site or a mobile web site,
including any email services provided through the specified site, Your Designated Application
cannot exceed a monthly unique audience of one million (1,000,000), while at the same
time, Your Designated Application cannot generate more than ten million (10,000,000)
pageviews per month. For clarity, this audience metric is associated with the top level
domain associated with Your Designated Application and not a subdomain (by way of
example, weather.com is a top level domain; www.weather.com is a subdomain).
TWC shall use services provided by Nielsen Online, or another 3rd
party service, in TWC‟s sole
determination, to assess the size of the audience and the monthly pageviews associated with
Your Designated Application. If at any time, TWC determines that Your Designated
Application exceeds the established thresholds for the use of the Service, TWC may suspend
and/or terminate your subscription to the Service.
TWC Confidential Page 8 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
Metering
The Service is offered on a metered basis with a maximum allotment of two million (2,000,000)
data requests per API Key per subscription month. The Service is also throttled at 2,084 data
requests per minute per API Key to ensure that no single application or website can impact the
performance of the other applications and websites using the Service. If the TWC caching rules
outlined in this document are followed, assuming the maximum allotment of data requests per
API Key, a single API Key could maintain up-to-date weather information 24/7 for over 6,300
distinct location IDs per month.
Caching
While the Service will process all data requests made by Your Designated Application up to the
monthly data request allotment that you establish when you subscribe, making data requests
more frequently than the data is updated is inefficient and places undue burden on the hosting
infrastructure. TWC has established the following caching rules for use in optimizing your
subscription.
Location Details – cache for up to 12 hours per LocID;
Current Conditions – cache for up to 20 minutes per LocID;
Abbreviated U.S. Severe Weather Alerts – these are event driven and should not be
cached;
Forecast Data – cache for up to 60 minutes per LocID;
Sunrise/Sunset information – cache for up to 12 hours per LocID;
Climatology information – cache for up to 12 hours per LocID;
Maps
o Doppler Radar Maps – cache for up to 15 minutes;
o Forecast Maps – cache for up to 60 minutes;
Technology Platforms
The use of the Service is limited to (i) world wide web sites designed for access on a personal
computer by a traditional web browser (such as Microsoft Internet Explorer or Mozilla Firefox)
and optimized for viewing from a distance of one to three feet, (ii) downloadable personal
computer applications optimized for display on a personal computer screen from a distance of
from one to three feet, including, by way of example, widgets, gadgets, toolbars and browser
extensions, (iii) mobile web sites designed for access on a mobile device through a mobile web
browser and optimized for viewing from a distance of less than one foot, and/or (iv)
downloadable mobile phone and mobile smart phone applications designed or optimized for
mobile phone devices, and made available through commercial “storefronts”; in each case
identified in your registration for your Subscription and for which a unique API Key is
generated. Each of Your Designated Applications includes any email services provided through
the specified site or application. Your Designated Application, however, specifically excludes
TWC Confidential Page 9 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
applications designed or optimized for tablets, e-Readers and similar devices such as, for
example, the iPad, Galaxy, and Kindle devices.
If Your Designated Application utilizes a technology platform other than one of the
approved platforms identified above, you may not use the Service. Please contact the TWC
Revenue Management and Optimization department by calling (770) 226-2329 and selecting
option 8, between the hours of 9:30 am and 6:30 pm ET, excluding holidays. TWC
representatives will be happy to discuss your specific situation and explore potential alternatives.
Sharing API Keys
A subscription to the Service is created based on a number of unique inputs supplied by you.
These inputs include the domain name or application name that you designate for use with the
Service, the Technology Platform to be associated with Your Designated Application, and the
number of data requests that you designate should be allowed to be consumed by Your
Designated Applications during a subscription month. These inputs, among others, are used to
determine the subscription price and upon successfully processing payment for a subscription, to
subsequently generate a unique API Key for use by Your Designated Application with the
Service. An API Key is issued separately for each of Your Designated Applications that will
utilize the Service. You may have many API Keys associated with your account. You may not
share an API Key with any other person or business entity or use an API Key with any other
application or website other than Your Designated Application on the Technology Platform
designated at the time of API Key generation.
1.1.5. The Weather Channel API Implementation Guide
Once you subscribe to the Service, the Service will allow you to access the data set associated
with your subscription plan. This document, The Weather Channel® API Implementation Guide
(the “Guide”), describes the technical details of requesting data and using the Service. The
complete terms and conditions surrounding the use of the Service are set forth in the End User
Agreement. If you have any technical questions about the use of The Weather Channel API or
The Weather Channel API Console, please e-mail your question to: API-
[email protected]. For general questions about the Service including questions about
the End User Agreement or this Guide, please contact TWC via e-mail at
[email protected] or call The Weather Channel API Hotline at (770) 226-
2329 and select option 8. For questions regarding billing, please e-mail your question to: API-
[email protected] with a carbon copy to [email protected]. A
Billing Support representative should contact you via e-mail within 1 business day of your
submission.
1.2. Security
Access security is enforced within the Service using API Keys. When making requests of the
Service, you must pass an approved API key to retrieve data.
TWC Confidential Page 10 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
1.2.1. Security - API Keys
API Keys are unique identifiers. API Keys are associated with a billing account, a specific
subscription plan, a specific authorized application and/or authorized website domain and a
specific authorized technology platform. A valid API Key allows access to specific commands
associated with the Service for a defined period of time (either a subscription month or a
subscription year) and for a defined number of data requests during a monthly subscription
period which commences on the anniversary date of the subscription and renews monthly upon
receipt of payment or automatically for active, prepaid annual plans. Note: Annual plans do not
get an aggregated bucket of data requests that can be used at any time throughout the term of the
subscription; they get the number of monthly data requests established by the subscriber at the
time when the subscription was processed. Any unused data requests at the end of a subscription
month expire. They do not carry over into the following month.
TWC suggests that when testing, you use The Weather Channel API Console and your Magic
Key; use of this console will not impact your aggregate bucket of monthly data requests.
API Keys must be passed via the URL “apikey” parameter with every Service request.
An example of a properly formatted request for current conditions for U.S. zip code 30339 using
the apikey parameter is shown below (note: the key in this example is not a valid key):
http://api.theweatherchannel.com/data/trupoint_cc/30339?doctype=xml&apikey=c1a56a7d-
e149-41ad-9ddb&country=US
1.3. Supported Languages and Locales
The following list indicates locale codes that can be passed to the Service to retrieve
internationalized data, where translations are available. These codes will only work with
subscriptions that have been authorized for a specific language. For example if you select
Spanish as a language to be associated with your subscription, then the codes es_AR, es_ES,
es_MX, and es_US will be authorized. You can select any one of 5 available languages as your
default language: English, Spanish, French, German, or Portuguese. This language is included in
the base cost of a subscription; additional languages are available for a small incremental fee.
Locale Language Country
de_DE German Germany
en_GB English England
en_IN English India
en_US English United States
es_AR Spanish Argentina
es_ES Spanish Spain
es_MX Spanish Mexico
es_US Spanish United States
fr_FR French France
pt_BR Portuguese Brazil
TWC Confidential Page 11 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
2. IMPLEMENTATION
2.1. URLs
The Service is accessible at:
http://api.theweatherchannel.com/data/
The general format for URLs associated with the Service is as follows:
http://api.theweatherchannel.com/data/{command}/{location}?doctype={format}&country={co
untry}&locale={locale}&units={units}&apikey={apikey}{¶meters}
where:
command: Any valid Service command.
location: Any valid location ID returned by the Service search function or U.S. zip
code or U.K. postal code, or French postal code, or German postal code.
All U.S. zip codes and U.K. postal codes, and French postal codes, and
German postal codes are valid LocIDs and do not require a search. The
location is case sensitive. Please use uppercase.
format: either xml or json
country: A country designation is only used with U.S. zip codes, U.K. postal codes,
French postal codes, and German postal codes to ensure that there is no
duplication of zip/postal codes across countries. The country code FR is
used for France; GM for Germany; UK for United Kingdom; and US for
the United States. If you are using a zip code/postal code, this field is
required.
locale: The locale is used to specify the weather phrase, pressure description,
wind direction text, and UV text in the language requested. The “blunt
phrase” remains in English. For French use fr_FR; For German use
de_DE; for Portuguese use pt_BR; for English use either en_GB in the
United Kingdom, en_IN in India, or en_US in the United States; and for
Spanish use either es_AR in Argentina, es_ES in Spain, es_MX in
Mexico, or es_US in the United States. The locale is associated with the
language(s) of your subscription. If you did not subscribe to a specific
language then the locale values associated with that language will not
work.
TWC Confidential Page 12 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
units: “m” for metric units or “s” for standard units. This value affects items
such as whether temperature is returned in Celsius or Fahrenheit or if wind
speed is returned in km/h or mph or if visibility is returned in km or miles.
apikey: a valid API Key is issued once a subscription is accepted by TWC and
initial payment is rendered. An API Key is required for data to be
returned by the Service.
parameters certain commands will accept additional parameters to alter the data
returned by a command. Sample parameters include such items as the
“&day=” parameter, the “&days=” parameter, the “&start=” parameter,
and the “&end=” parameter. Parameters are discussed in more detail as
part of the individual command section of this document. Note that
passing request parameters via POST is not supported.
Example: to request a 5-day data forecast for U.K. postal code SW1P in XML format in metric
units in the English language, a correctly formatted call to the Service would look like:
http://api.theweatherchannel.com/data/df/SW1P?doctype=xml&country=UK&locale=en_GB&u
nits=m&apikey=c1a56a7d-e149-41ad-9ddb&day=0,1,2,3,4
Remember that a valid API Key must be passed with every data request, including the example
above. An “Invalid API Key” error will be returned if no API Key is passed.
2.1.1. The Image Service
The Image Service is also accessible at:
http://api.theweatherchannel.com/image/
The general format for URLs associated with the Image Service is as follows:
http://api.theweatherchannel.com/image/{map_name}-
{map_size}?doctype={format}&apikey={apikey}
where:
map_name: For U.S. National Maps:
NatlDplr National Doppler Radar Map
NatlPrecip National Precipitation Forecast Map
NatlHigh Today's Forecasted Highs
NatlLow Tonight's Forecasted Lows
For U.S. Regional Maps:
AkDplr Alaska Doppler Radar
TWC Confidential Page 13 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
CnDplr Central Region Doppler Radar
CnPrecip Central Region Precipitation Forecast Map
CnHigh Today's Forecasted Highs for the Central Region
CnLow Tonight's Forecasted Lows for the Central Region
EcDplr East Central Region Doppler Radar
EcPrecip East Central Region Precipitation Forecast Map
EcHigh Today's Forecasted Highs for the East Central Region
EcLow Tonight's Forecasted Lows for the East Central Region
HiDplr Hawaii Doppler Radar
NcDplr North Central Region Doppler Radar
NcPrecip North Central Region Precipitation Forecast Map
NcHigh Today's Forecasted Highs for the North Central Region
NcLow Tonight's Forecasted Lows for the North Central Region
NeDplr Northeast Region Doppler Radar
NePrecip Northeast Region Precipitation Forecast Map
NeHigh Today's Forecasted Highs for the Northeast Region
NeLow Tonight's Forecasted Lows for the Northeast Region
NwDplr Northwest Region Doppler Radar
NwPrecip Northwest Region Precipitation Forecast Map
NwHigh Today's Forecasted Highs for the Northwest Region
NwLow Tonight's Forecasted Lows for the Northwest Region
PrDplr Puerto Rico / U.S. VI Doppler Radar
ScDplr South Central Region Doppler Radar
ScPrecip South Central Region Precipitation Forecast Map
ScHigh Today's Forecasted Highs for the South Central Region
ScLow Tonight's Forecasted Lows for the South Central Region
SeDplr Southeast Region Doppler Radar
SePrecip Southeast Region Precipitation Forecast Map
SeHigh Today's Forecasted Highs for the Southeast Region
SeLow Tonight's Forecasted Lows for the Southeast Region
SwDplr Southwest Region Doppler Radar
SwPrecip Southwest Region Precipitation Forecast Map
SwHigh Today's Forecasted Highs for the Southwest Region
SwLow Tonight's Forecasted Lows for the Southwest Region
WcDplr West Central Region Doppler Radar
WcPrecip West Central Region Precipitation Forecast Map
WcHigh Today's Forecasted Highs for the West Central Region
WcLow Tonight's Forecasted Lows for the West Central Region
map_size: Lg 600x405 pixels
Md 440x297 pixels
Sm 277x187 pixels
doctype: img
TWC Confidential Page 14 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
apikey: a valid API Key is issued once a subscription is accepted by TWC and
initial payment is rendered. An API Key is required for images to be
returned by the Image Service.
Example: to request a 440x297 pixel National Doppler Radar map, a correctly formatted call to
the Image Service would look like:
http://api.theweatherchannel.com/image/NatlDplr-Md?doctype=img&apikey=c1a56a7d-e149-
41ad-9ddb
2.2. CallBack Parameters
The Service supports JSON callback functionality.
Each JSON result can have an optional callback parameter „cb‟ and function name appended to
the URL.
Below is an example of a JSON result using the callback parameter.
http://api.theweatherchannel.com/data/df/ASXX0112?doctype=json&cb=my_foo&apikey=c1a5
6a7d-e149-41ad-9ddb
my_foo([{"key":"94768000",
"class":"forecast",
"validDate":1316595600,
"maxTemp":72,
"minTemp":55,
"precip_type":"rain",
"day":{"humid":39,
"wSpeed":8,
"wDir":338,
"pop":0,
"uv":6,
"icon":32,
"wDirText":"NNW",
"phrase":"Sunny",
"bluntPhrase":"Sunny",
"precip_type":"rain",
"snwAccumPhrase":"",
"weatherCode":"3200"},
"night":{"humid":64,
"wSpeed":6,
"wDir":299,
"pop":0,
"uv":0,
"icon":31,
"wDirText":"WNW",
"phrase":"Clear",
"bluntPhrase":"Clear",
"precip_type":"rain",
TWC Confidential Page 15 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
"snwAccumPhrase":"",
"weatherCode":"3100"}}])
2.3. General Command Overview
Command Name Command
ID
Usage URL example
Location Search locsearch Search function utilized to return a
proprietary TWC LocID for a
specified worldwide city name (not
available to single city subscribers)
OPTIONAL
…/locsearch/london?doctype=xml
…/locsearch/london?doctype=json
…/locsearch/london?doctype=json&cb=func
_name
Location loc Consolidated location information
including location key (LocID),
latitude, longitude, elevation, time
zone offset, zone information, city
name, state (if applicable), and
country. In the U.S., U.K., France,
and Germany the zip code/postal
code is also provided. Additionally,
in the U.S., the dma and regional
map identifiers are provided for a
specified location.
OPTIONAL
…/loc/USGA0028?doctype=xml
…/loc/USGA0028?doctype=json
…/loc/USGA0028?doctype=json&cb=func_
name
…/loc/SW1P?doctype=xml&country=countr
y_code
…/loc/SW1P?doctype=json&country=countr
y_code
…/loc/SW1P?doctype=json&cb=func_name
&country= country_code
TruPoint
Current
Conditions
trupoint_cc Current weather information
(observations) for a specified
worldwide city, U.S. zip code, or
French, German, or United
Kingdom postal code.
OPTIONAL
…/trupoint_cc/30034?doctype=xml
…/trupoint_cc/30034?doctype=json
…/trupoint_cc/30034?doctype=json&cb=fun
c_name
…/trupoint_cc/SW1P?doctype=xml&country
=country_code
…/trupoint_cc/SW1P?doctype=json&countr
y=country_code
…/trupoint_cc/SW1P?doctype=json&cb=fun
c_name&country= country_code
Abbreviated U.S.
Severe Weather
Alerts
svr Event driven, abbreviated U.S.
severe weather alert information
from the National Weather Service,
localized for U.S. cities and U.S.
zip codes. Limited to the
continental United States Only.
Information is currently only
available in the English language.
Abbreviated U.S. severe weather
alert information includes such
information as a headline (by way
of example: “Flash Flood Watch in
effect from 6PM MDT TUE until
NOON MDT WED”), the name of
the U.S. county affected, the
severity level of the alert, and the
…/svr/USGA0028?doctype=xml
…/svr/USGA 0028?doctype=json
…/svr/USGA0028?doctype=json&cb=func_
name
…/svr/30339?doctype=xml
…/svr/30339?doctype=json
…/svr/30339?doctype=json&cb=func_name
TWC Confidential Page 16 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
start and end time of the alert. If
there are no active alerts present,
the resulting data set may be blank.
OPTIONAL
Sunrise/Sunset ss Sunrise / Sunset time for a specified
location
OPTIONAL
days = [ 1..5 ]
A value of 1 indicates a desire for
today‟s sunrise/sunset information; a
value of 2 indicates a desire for
today and tomorrow‟s sunrise /
sunset information and so on.
…/ss/USGA0028?doctype=xml&days=5
…/ss/ USGA0028?doctype=json&days=5
…/ss/USGA0028?doctype=json&days=5&c
b=func_name
…/ss/SW1P?doctype=xml&days=5&country
=country_code
…/ss/SW1P?doctype=json&days=5&country
=country_code
…/ss/SW1P?doctype=json&days=5&cb=fun
c_name&country=country_code
Daily Data
Forecast
df Daily daypart data forecast in two
(2) twelve hour day parts (a 12 hour
“day” day part and a 12 hour
“night” day part). The daytime day
part goes from 7 am to 7 pm local
time and the night time day part
goes from 7 pm to 7 am local time.
OPTIONAL
day = [ 0..4 ]
A value of 0 indicates a desire for
today‟s daypart forecast; a value of
1 indicates a desire for tomorrow‟s
daypart forecast, a value of 2
indicates a desire for the day after
tomorrow‟s daypart forecast and so
on.
…/df/ USGA0028?doctype=xml
…/df/ USGA0028?doctype=json
…/df/USGA0028?doctype=json&cb=func_n
ame
…/df/USGA0028?doctype=xml&day=0,1,2,
3,4
…/df/SW1P?doctype=xml&country=country
_code
…/df/SW1P?doctype=json&country=country
_code
…/df/SW1P?doctype=json&cb=func_name
&country=country_code
…/df/SW1P?doctype=xml&country=country
_code&day=0,1,2,3,4
Daily Narrative
(Text) Forecast
dn Daily narrative (text) forecast (by
way of example: Thunderstorms
during the morning hours, then skies
turning partly cloudy during the
afternoon. High 59F. Winds ENE at
5 to 10 mph) in two (2) twelve hour
dayparts for the first 48 hours. The
daytime day part goes from 7 am to
7 pm local time and the night time
day part goes from 7 pm to 7 am
local time. All days more than 1 day
in the future contain a single
daytime daypart. Currently only
available in the English language.
OPTIONAL
day = [ 0..4 ]
…/dn/ USGA0028?doctype=xml
…/dn/ USGA0028?doctype=json
…/dn/USGA0028?doctype=json&cb=func_n
ame
…/dn/USGA0028?doctype=xml&day=0,1,2,
3,4
…/dn/SW1P?doctype=xml&country=countr
y_code
…/dn/SW1P?doctype=json&country=countr
y_code
…/dn/SW1P?doctype=json&cb=func_name
&country=country_code
…/dn/SW1P?doctype=xml&country=countr
y_code&day=0,1,2,3,4
TWC Confidential Page 17 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
A value of 0 indicates a desire for
today‟s daypart forecast; a value of
1 indicates a desire for tomorrow‟s
daypart forecast, a value of 2
indicates a desire for the day daypart
forecast for the day after tomorrow
and so on.
Climatology
(Monthly
Averages)
avg Climatology data (average monthly
high temperature and average
monthly low temperature for a
specified worldwide city, U.S. zip
code or French, German, or U.K.
postal code. In the U.S., additional
data includes the monthly mean
temperature, average monthly
precipitation, and the record high
temperature in a month, the record
low temperature in a month, and the
year associated with the record.
Outside the U.S., monthly mean
temperature and average
precipitation is also made available
if TWC has access to this
information.
OPTIONAL
start=[ time in epoch ]
end=[ time in epoch ]
…/avg/USGA0028?doctype=xml&start=130
0896260&end=1300996260
…/avg/USGA0028?doctype=json&start=130
0896260&end=1300996260
…/avg/USGA0028?doctype=json&start=130
0896260&end=1300996260&cb= func_name
…/avg/SW1P?doctype=xml&country=countr
y_code&start=1300896260&end=130099626
0
…/avg/SW1P?doctype=json&country=count
ry_code&start=1300896260&end=13009962
60
…/avg/SW1P?doctype=json&country=count
ry_code&start=1300896260&end=13009962
60&cb= func_name
2.4. Daily Data Forecast
The “df” Command ID is used to display the daily data forecast for a given worldwide city, U.S.
zip code, or French, German, or U.K. postal code. It returns the daily data forecast broken out
into a daytime and nighttime daypart forecast for each requested day, up to a total of 5 forecast
days and 10 forecast dayparts. Note that the daytime daypart values will not be displayed after 3
pm local time of the current day as the data becomes invalid at that time.
Daytime daypart data is returned under the parent <day> node, and nighttime daypart data under
the <night> node. Maximum and minimum temperatures, which can occur at any point during
the day, are represented by <maxTemp> and <minTemp> outside of the daypart nodes.
2.4.1. Sample URLs (Daily Data Forecast)
1. XML format
http://api.theweatherchannel.com/data/df/USGA0028?doctype=xml
http://api.theweatherchannel.com/data/df/SW1P?doctype=xml&country=UK
2. JSON format
http://api.theweatherchannel.com/data/df/USGA0028?doctype=json
http://api.theweatherchannel.com/data/df/SW1P?doctype=json&country=UK
TWC Confidential Page 18 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
3. Optional Parameter (day)
Today’s forecast (if no day parameter is passed, this is the default):
http://api.theweatherchannel.com/data/df/USGA0028?doctype=xml&day=0
http://api.theweatherchannel.com/data/df/SW1P?doctype=xml&country=UK&da
y=0
Five data forecast days:
http://api.theweatherchannel.com/data/df/USGA0028?doctype=xml&day=0,1,2
,3,4
http://api.theweatherchannel.com/data/df/SW1P?doctype=xml&country=UK&da
y=0,1,2,3,4
2.4.2. Parameters
Daily Forecast supports the following optional parameter:
Parameter Description
day Filters the forecast based on a
Day Number (0…4)
day=0 is today;
day=1 is tomorrow;
day=2 is the day after tomorrow;
day=3 is the day after that;
day=4 is the day after day 3
The “day” attribute will be used to specify which forecast day(s) to return. Day numbers can be
separated by commas to request multiple forecast days.
The default result set will be the current day‟s forecast or where “day=0”.
2.4.3. Data Nodes (Daily Data Forecast)
Daily Forecast returns the following Nodes and Attributes:
XML element Description
validDate Requested forecast date expressed in epoch
format/UTC
maxTemp* High temperature
minTemp Low temperature
Precip_type Type of precipitation
humid Humidity
wSpeed Wind speed
wdir Wind direction (degrees)
pop Precipitation chance
uv UV index (day only)
icon TWC weather icon number
wDirText Wind direction (cardinal)
phrase Weather phrase (in specified language)
bluntPhrase Weather phrase, less than 12 chars (in
TWC Confidential Page 19 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
English only
snwAccumPhrase ** Future Use **
*maxTemp is part of the daytime forecast and will be empty after 3 pm local time.
2.4.4. Sample results (Daily Data Forecast)
<forecasts>
<forecast key="03779000">
<class>forecast</class>
<validDate>1316628000</validDate>
<maxTemp>63</maxTemp>
<minTemp>52</minTemp>
<precip_type>rain</precip_type> <day>
<humid>69</humid>
<wSpeed>12</wSpeed>
<wDir>248</wDir>
<pop>70</pop>
<uv>3</uv>
<icon>11</icon>
<wDirText>WSW</wDirText>
<phrase> AM Light Rain</phrase> <bluntPhrase>AM Lgt Rain</bluntPhrase>
<precip_type>rain</precip_type>
<snwAccumPhrase/>
<weatherCode>6304</weatherCode>
</day>
<night>
<humid>72</humid>
<wSpeed>12</wSpeed>
<wDir>246</wDir>
<pop>0</pop>
<uv>0</uv>
<icon>31</icon>
<wDirText>WSW</wDirText>
<phrase>Clear</phrase>
<bluntPhrase>Clear</bluntPhrase>
<precip_type>rain</precip_type>
<snwAccumPhrase/>
<weatherCode>3100</weatherCode>
</night>
</forecast>
</forecasts>
2.5. Narrative Forecast
The “dn” Command ID is used to display the daily narrative (text) forecast for a given
worldwide city, U.S. zip code, or French, German, or U.K. postal code. By default the
Command ID will return the day and night forecasts for the first 24 hours. Narrative forecasts
can be displayed for up to 4 days in the future. Requests for information greater than 1 day into
the future will show only a single daypart forecast for that day.
TWC Confidential Page 20 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
2.5.1. Sample URLs (Narrative Forecast)
XML format
http://api.theweatherchannel.com/data/dn/USGA0028?doctype=xml
http://api.theweatherchannel.com/data/dn/SW1P?doctype=xml&country=UK
2. JSON format
http://api.theweatherchannel.com/data/dn/USGA0028?doctype=json
http://api.theweatherchannel.com/data/dn/USGA0028?doctype=json&cb=my_fo
o
http://api.theweatherchannel.com/data/dn/SW1P?doctype=json&country=UK
http://api.theweatherchannel.com/data/dn/SW1P?doctype=json&country=UK&c
b=my_foo
2.5.2. Parameters (Narrative Forecast)
Narrative Forecast returns the following data elements:
Node Description
day Filters the forecast based on a Day Number
(0…4).
day=0 is today;
day=1 is tomorrow;
day=2 is the day after tomorrow;
day=3 is the day after that;
day=4 is the day after day 3
The “day” attribute will be used to specify which forecast day(s) to return. Day numbers can be
separated by commas to request multiple forecast days.
2.5.3. Data Nodes (Narrative Forecast)
Daily Forecast returns the following Nodes and Attributes:
XML element Description
validDate Requested forecast date expressed in epoch
format/UTC
dayPart Either day or night
phrase Weather phrase
uv UV index (day only)
icon TWC weather icon number
2.5.4. Sample results (Narrative Forecast)
<narrativeForecasts>
<narrativeForecast key="03779000">
<class>narrativeForecast</class>
<validDate>1316599200</validDate>
<dayPart>Today</dayPart>
<phrase>Becoming partly cloudy after some morning light rain. High 63F.
Winds WSW at 10 to 15 mph. Chance of rain 70%.</phrase>
<uv>3</uv>
TWC Confidential Page 21 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
<icon>11</icon>
<weatherCode>6304</weatherCode>
</narrativeForecast>
<narrativeForecast key="03779000">
<class>narrativeForecast</class>
<validDate>1316642400</validDate>
<dayPart>Tonight</dayPart>
<phrase>Generally clear. Low 52F. Winds WSW at 10 to 15 mph.</phrase>
<uv/>
<icon>31</icon>
<weatherCode>3100</weatherCode>
</narrativeForecast>
</narrativeForecasts>
2.6. Abbreviated U.S. Severe Weather Alerts
The “svr” Command ID is used to display a list of abbreviated U.S. Severe Weather Alerts for a
given U.S. city or U.S. zip code in the continental United States. Abbreviated U.S. Severe
Weather Alerts are event driven. If one or multiple severe alerts are found for a given U.S. city
or U.S. zip code in the continental United States, they will be returned and displayed in the
format shown below. If no alerts are valid for the specified location, an empty primary node will
be returned. Abbreviated U.S. Severe Weather Alerts are currently only available in the English
language and only apply to U.S. cities and U.S. zip codes in the continental United States of
America.
2.6.1. Sample URLs (Abbreviated U.S. Severe Weather Alerts)
1. XML format
http://api.theweatherchannel.com/data/svr/USGA0028?doctype=xml
http://api.theweatherchannel.com/data/svr/30339?doctype=xml
2. JSON format
http://api.theweatherchannel.com/data/svr/USGA0028?doctype=json
http://api.theweatherchannel.com/data/svr/USGA0028?doctype=json&cb=my_f
oo
http://api.theweatherchannel.com/data/svr/30339?doctype=json
http://api.theweatherchannel.com/data/svr/30339?doctype=json&cb=my_foo
2.6.2. Data Nodes (Abbreviated U.S. Severe Weather Alerts)
Abbreviated U.S. Severe Weather Alerts returns the following data elements:
Node Description
alert areaId Zone
issueOffice NWS office that issued the alert
phenomenaCode Type of alert
significance Type of significant event, e.g. watch,
warning, advisory
headline Short summary of the alert
description Alert title
textId TWC key for fetching alerts
areaName County
TWC Confidential Page 22 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
severity Severity level (1= most severe; 3 = least
severe)
beginTime Start time of the alert, if available (in
epoch format/UTC)
endTime End time of the alert, if available (in epoch
format/UTC)
2.6.3. Sample results (Abbreviated U.S. Severe Weather Alerts)
<alerts>
<alert areaId="ALC017" issueOffice="KBMX" etn="0064" phenomenaCode="FF"
significance="W">
<class>alert</class>
<headline>Flash Flood Warning in effect until 12AM CDT WED
</headline>
<description>Flash Flood Warning</description>
<textId>122243</textId>
<areaName>Chambers</areaName>
<severity>1</severity>
<beginTime/>
<endTime>1316581200</endTime>
</alert>
</alerts>
2.7. TruPoint Current Conditions
The “trupoint_cc” Command ID is used to display the most recent current conditions
(observation) data for a given worldwide city, U.S. zip code, or French, German, or U.K. postal
code. Current conditions data is updated in The Weather Channel API three (3) times per hour
for U.S. cities and zip codes and hourly across the rest of the world. These updates occur at
approximately five (5), twenty-five (25), and forty-five (45) minutes after the hour. Please note
that there could be a delay of up to 5 minutes following the update time before the updated data
is replicated across our server pool. Making data requests at ten minutes past, thirty minutes
past, and fifty minutes past the hour may ensure that you are accessing the latest data updates.
2.7.1. Sample URLs (TruPoint Current Conditions)
1. XML format
http://api.theweatherchannel.com/data/trupoint_cc/USGA0028?doctype=xml
http://api.theweatherchannel.com/data/trupoint_cc/SW1P?doctype=xml&country=UK
2. JSON format
http://api.theweatherchannel.com/data/trupoint_cc/USGA0028?doctype=json
http://api.theweatherchannel.com/data/trupoint_cc/USGA0028?doctype=json&cb=my_fo
o
http://api.theweatherchannel.com/data/trupoint_cc/SW1P?doctype=json&country=UK
http://api.theweatherchannel.com/data/trupoint_cc/USGA0028?doctype=json&country=
UK&cb=my_foo
TWC Confidential Page 23 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
2.7.2. Data Nodes (TruPoint Current Conditions)
Node Description
Observation key Observation station
visibility Visibility distance
date Time of last observation, expressed
in epoch format (time zone GMT)
wxIcon TWC weather icon number
temp Temperature
dewPoint Dew point
pressure Barometric pressure
pressureDescription Description of the pressure
feelsLike Feels like temperature
Humid Humidity
wSpeed Wind speed
wGust Wind gusts
wDir Wind direction (degrees)
tend Barometric tendency
uv UV index
uvText UV index description
obsName Station name
wDirText Wind direction (cardinal)
text Weather text
qualifier
blunt_phrase
terse_phrase
2.7.3. Sample results (TruPoint Current Conditions)
<observation key="T03779000">
<class>observation</class>
<visibility>6.0</visibility>
<date>1316628300</date>
<wxIcon>29</wxIcon>
<temp>61</temp>
<dewPoint>45</dewPoint>
<pressure>30.0</pressure>
<pressureDescription>Steady</pressureDescription>
<feelsLike>61</feelsLike>
<humid>55</humid>
<wSpeed>15</wSpeed>
<wGust />
<wDir>250</wDir>
<tend>0</tend>
<uv>0</uv>
<uvText>Low</uvText>
<obsName>London City Airport</obsName>
<wDirText>WSW</wDirText>
<text>Partly Cloudy</text>
<qualifier><![CDATA[Seasonal temperatures.]]></qualifier>
<blunt_phrase><![CDATA[Seasonal temperatures.]]></blunt_phrase>
<terse_phrase><![CDATA[Seasonal temperatures.]]></terse_phrase>
</observation>
TWC Confidential Page 24 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
2.8. Locations
The “loc” Command ID is used to display geographic details about a given worldwide city, U.S.
zip code, or French, German, or U.K. postal code. This includes any data that TWC has captured,
including values such as country, state, zip code, and lat/lon. This data can be used to retrieve
data from other Service commands.
2.8.1. Sample URLs (Locations)
1. XML format
http://api.theweatherchannel.com/data/loc/USGA0026?doctype=xml
http://api.theweatherchannel.com/data/loc/SW1P?doctype=xml&country=UK
2. JSON format
http://api.theweatherchannel.com/data/loc/USGA0028?doctype=json
http://api.theweatherchannel.com/data/loc/USGA0028?doctype=json&cb=my_foo
http://api.theweatherchannel.com/data/loc/SW1P?doctype=json&country=UK
http://api.theweatherchannel.com/data/loc/SW1P?doctype=json&country=UK&cb=my_f
oo
2.8.1.1. Countries with Overlapping Zip Codes / Postal Codes
There are several countries that have zip codes and/or postal codes that overlap with other
countries. To ensure that you are returned the proper data for a zip code / postal code, you will
be required to specify the Country Code when requesting a zip code or postal code. This is
done by adding the “&country=” parameter. For example:
In the U.S: http://api.theweatherchannel.com/data/loc/30339?doctype=xml&country=US
In the U.K.: http://api.theweatherchannel.com/data/loc/SW1P?doctype=xml&country=UK
In Germany: http://api.theweatherchannel.com/data/loc/04758?doctype=xml&country=GM
In France: http://api.theweatherchannel.com/data/loc/75000?doctype=xml&country=FR
Below is a list of countries with zip codes / postal codes that may overlap, along with the
Country Code to utilize to ensure the proper data is returned when using a zip code / postal code
associated with this country.
Country Name Country Code
France FR
Germany GM
United Kingdom UK
United States US
2.8.2. Data Nodes (Locations)
Node Description Location key TWC location
type TWC location type
countryCode Country Code
TWC Confidential Page 25 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
lat Latitude
lng Longitude
name Unique TWC location Id
elev Elevation
tz GMT timezone offset
zoneInfo Olson db time zone name
name Display name
city City name
state State/Province
country Country name
forecastID Unique forecast Id
obsID Observation Id
dma U.S. DMA code
rgn4 TWC region-4 map code
rgn9 TWC region-9 map code
zip If applicable, zip code / postal code
parentLoc Parent location Id
2.8.3. Sample results (Locations)
<location key="SW1P" type="4" countryCode="UK">
<class>location</class>
<lat>51.49530029296875</lat>
<lng>-0.13729999959468842</lng>
<elv>46</elv>
<tz>1.0</tz>
<zoneInfo>Europe/London</zoneInfo>
<name>London</name>
<city>London</city>
<state>ENG</state>
<country>United Kingdom</country>
<forecastID>03779000</forecastID>
<obsID>03770</obsID>
<dma />
<rgn4 />
<rgn9 />
<zip>SW1P</zip>
<parentLoc>UKXX0085</parentLoc>
</location>
2.10. Location Search
The “locsearch” Command ID is used to search for a TWC location ID by worldwide city name.
The “locsearch” Command ID returns the geographic details about all the cities that it matches.
This includes any data that TWC has captured, including values such as country, state, zip code,
and lat/lon.
2.10.1. Sample URLs (Location Search)
1. XML format
http://api.theweatherchannel.com/data/locsearch/london?doctype=xml
TWC Confidential Page 26 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
2. JSON format
http://api.theweatherchannel.com/data/locsearch/london?doctype=json
http://api.theweatherchannel.com/data/locsearch/london?doctype=json&cb=my_foo
2.10.2. Data Nodes (Location)
Node Description
location key TWC location
type TWC location type
countryCode Country Code
score Match rating
lat Latitude
lng Longitude
elev Elevation
tz GMT timezone offset
zoneInfo Olson db time zone name
name Display name
city City name
state State/Province
country Country name
forecastID Unique forecast Id
obsID Observation Id
dma U.S. DMA code
rgn4 TWC region-4 map code
rgn9 TWC region-9 map code
zip If applicable, zip code/postal code
parentLoc Parent location Id
2.10.3. Sample results (Location Search)
<results>
<errors />
<location key="UKXX0085" type="1" countryCode="UK" score="0.99999994">
<class>location</class>
<lat>51.500152587890625</lat>
<lng>-0.12623600661754608</lng>
<elv>56</elv>
<tz>1.0</tz>
<zoneInfo>Europe/London</zoneInfo>
<name>London</name>
<city>London</city>
<state>ENG</state>
<country>United Kingdom</country>
<forecastID>03779000</forecastID>
<obsID>EGLC</obsID>
<dma />
<rgn4 />
<rgn9 />
<zip>SW99</zip>
<parentLoc />
</location>
TWC Confidential Page 27 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
<location key="CAXX0255" type="1" countryCode="CA" score="0.99999994">
<class>location</class>
<lat>42.98688888549805</lat>
<lng>-81.24620819091797</lng>
<elv>896</elv>
<tz>-4.0</tz>
<zoneInfo>America/Montreal</zoneInfo>
<name>London</name>
<city>London</city>
<state>ON</state>
<country>Canada</country>
<forecastID>71623000</forecastID>
<obsID>CYXU</obsID>
<dma />
<rgn4 />
<rgn9 />
<zip>CAXX0255</zip>
<parentLoc />
</location>
</results>
2.11. Sunrise/Sunset
The “ss” Command ID is used to display the sunrise & sunset times for a given worldwide city,
U.S. zip code, or French, German, or U.K. postal code.
2.11.1. Sample URLs (Sunrise/Sunset)
1. XML format
http://api.theweatherchannel.com/data/ss/USGA0028?doctype=xml&days=5
http://api.theweatherchannel.com/data/ss/SW1P?doctype=xml&country=UK&days=5
2. JSON format
http://api.theweatherchannel.com/data/ss/USGA0028?doctype=json&days=5
http://api.theweatherchannel.com/data/ss/USGA0028?doctype=json&days=5&cb=my_fo
o
http://api.theweatherchannel.com/data/ss/SW1P?doctype=json&country=UK&days=5
http://api.theweatherchannel.com/data/ss/USGA0028?doctype=json&country=UK&days
=5&cb=my_foo
2.11.2. Parameters (Type Sunrise/Sunset)
Sunrise/sunset supports the following optional parameters:
Parameter Description
days The number of days to return [1..5]
The “&days=” parameter will be used to specify how many forecast days to return,
TWC Confidential Page 28 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
where:
days=1 returns today,
days=2 returns today & tomorrow,
days=3 returns today, tomorrow, and day 3
days=4 returns today, tomorrow, day 3, and day 4
days=5 returns today, tomorrow, day 3, day 4, and day 5
If you do not specify the number of days, the default is days=1.
2.11.3. Data Nodes (Sunrise/Sunset)
XML element Description
rise Sunrise expressed in epoch
format/UTC
set Sunset expressed in epoch
format/UTC
2.11.4. Sample results (Sunrise/Sunset)
<riseSet>
<sunRiseSet>
<rise>1316583840</rise>
<set>1316628120</set>
</sunRiseSet>
<sunRiseSet>
<rise>1316670360</rise>
<set>1316714400</set>
</sunRiseSet>
<sunRiseSet>
<rise>1316756820</rise>
<set>1316800680</set>
</sunRiseSet>
<sunRiseSet>
<rise>1316843340</rise>
<set>1316886900</set>
</sunRiseSet>
<sunRiseSet>
<rise>1316929860</rise>
<set>1316973180</set>
</sunRiseSet>
</riseSet>
2.12. Climatology (Monthly Averages)
The “avg” Command ID returns the average monthly high temperature and average monthly low
temperature for a specified worldwide city, U.S. zip code or French, German, or U.K. postal
code. In the continental U.S., additional data includes the monthly mean temperature, the
TWC Confidential Page 29 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
average monthly precipitation, the record high temperature in a month, the record low
temperature in a month, and the year associated with the record. Outside the continental U.S.,
monthly mean temperature and average precipitation is also made available if TWC has access to
this information.
2.12.1. Sample URLs (Averages/Record)
1. XML format
http://api.theweatherchannel.com/data/avg/USGA0028?doctype=xml&start=1293840000
&end=1296518399
http://api.theweatherchannel.com/data/avg/SW1P?doctype=xml&country=UK&start=129
3840000&end=1296518399
2. JSON format
http://api.theweatherchannel.com/data/avg/USGA0028?doctype=json&start=1293840000
&end=1296518399
http://api.theweatherchannel.com/data/avg/SW1P?doctype=json&country=UK&start=12
93840000&end=1296518399
http://api.theweatherchannel.com/data/avg/USGA0028?doctype=json&cb=my_foo&start
=1293840000&end=1296518399
http://api.theweatherchannel.com/data/avg/SW1P?doctype=json&cb=my_foo&country=
UK&start=1293840000&end=1296518399
2.12.2. Parameters (Climatology (Averages/Records))
Averages/record supports the following optional parameters:
Parameter Description
start* The start time expressed in epoch format
end* The end time expressed in epoch format
* Start has to be less than or equal to end or it will result in an error.
2.12.3. Data Nodes (Climatology (Averages/Records))
XML element Description
validDate Date when the averages were
recorded in epoch format/UTC
avgHi Average high for that month
avgLo Average low for that month
monthlyMean Mean temperature for that month
avgPrecip Average precipitation for that month
recordHi Record high temperature for the
month
recordHiYr The year when the highest
temperature was recorded
TWC Confidential Page 30 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
recordLo Record low temperature for the
month.
recordLoYr The year when the lowest
temperature was recorded
2.12.4. Sample results (Climatology (Monthly Averages))
<averages>
<avgClimate>
<validDate>975646800</validDate>
<avgHi>48</avgHi>
<avgLo>37</avgLo>
<monthlyMean>43</monthlyMean>
<avgPrecip>2.13</avgPrecip>
<recordHi>N/A</recordHi>
<recordHiYr>N/A</recordHiYr>
<recordLo />
<recordLoYr>N/A</recordLoYr>
</avgClimate>
</averages>
2.13. The Weather Channel API Image Service
2.13.1. Map Imagery available for the United States of America
Map imagery for the United States is available in 3 sizes:
Small: 277 pixels x 187 pixels in size
Medium: 440 pixels x 297 pixels in size
Large: 600 pixels x 405 pixels in size
Example of Small Map:
TWC Confidential Page 31 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
Example of Medium Map:
Example of Large Map:
TWC Confidential Page 32 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
All map imagery contains the weather.com logo on the bottom right hand corner of the map.
The maps must be used in the sizes provided and may not be resized.
2.13.2. Sample URLs (U.S. National Maps)
Today‟s Forecasted Highs for the continental United States of America (Small Size)
http://api.theweatherchannel.com/image/NatlHigh-Sm?doctype=img&apikey={API_Key}
Tonight‟s Forecasted Lows for the continental United States of America (Small Size)
http://api.theweatherchannel.com/image/NatlLow-Sm?doctype=img&apikey={API_Key}
National Precipitation Forecast Map for the continental United States of America (Small Size)
http://api.theweatherchannel.com/image/NatlPrecip-Sm?doctype=img&apikey={API_Key}
TWC Confidential Page 33 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
National Doppler Radar Map for the continental United States of America (Small Size)
http://api.theweatherchannel.com/image/NatlDplr-Sm?doctype=img&apikey={API_Key}
2.13.3. Sample URLs (U.S. Regional Maps)
Today‟s Forecasted High for the Southeast Region (Small) (one of nine (9) U.S. regions defined by TWC)
http://api.theweatherchannel.com/image/SeHigh-Sm?doctype=img&apikey={API_Key}
Tonight‟s Forecasted Lows for the Southeast Region (Small) (one of the nine (9) U.S. regions defined by TWC)
http://api.theweatherchannel.com/image/SeLow-Sm?doctype=img&apikey={API_Key}
TWC Confidential Page 34 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
Southeast Regional Precipitation Forecast Map (Small) (one of the nine (9) U.S. regions defined by TWC)
http://api.theweatherchannel.com/image/SePrecip-Sm?doctype=img&apikey={API_Key}
Southeast Regional Doppler Radar Map (Small) (one of the nine (9) U.S. regions defined by TWC; each region
covers an area of approximately 1,800 miles)
http://api.theweatherchannel.com/image/SeDplr-Sm?doctype=img&apikey={API_Key}
Alaska Radar Map (Small) – a Doppler Radar map covering an area of approximately 2,100 miles that includes the
State of Alaska.
http://api.theweatherchannel.com/imageAkDplr-Sm?doctype=img&apikey={API_Key}
TWC Confidential Page 35 of 35 10/15/11
Copyright © 2011 The Weather Channel, LLC. All rights reserved. The Weather Channel® API Implementation Guide
The information contained herein is proprietary and confidential and may not be reproduced or retransmitted without the prior written consent of The Weather Channel, LLC.
Hawaii Radar Map (Small) – a Doppler Radar map covering an area of approximately 600 miles that includes the
State of Hawaii.
http://api.theweatherchannel.com/image/HiDplr-Sm?doctype=img&apikey={API_Key}
Puerto Rico / U.S. Virgin Islands Radar Map (Small) – a Doppler Radar map covering an area of approximately 600
miles that includes Puerto Rico and the United States Virgin Islands.
http://api.theweatherchannel.com/image/PrDplr-Sm?doctype=img&apikey={API_Key}