the weather channel® api implementation guide...the weather channel® api implementation guide the...

TWC Confidential 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




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




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




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;

http://portal.theweatherchannel.com/

http://portal.theweatherchannel.com/login-account.aspx?ReturnUrl=explore.aspx?launch=1

http://portal.theweatherchannel.com/login-account.aspx?ReturnUrl=explore.aspx?launch=1




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.




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.




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.

mailto:[email protected]

http://www.weather.com/




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




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.










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

http://api.theweatherchannel.com/data/trupoint_cc/30339?doctype=xml&apikey=c1a56a7d-e149-41ad-9ddb&country=US

http://api.theweatherchannel.com/data/trupoint_cc/30339?doctype=xml&apikey=c1a56a7d-e149-41ad-9ddb&country=US




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}{&parameters}

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.

http://api.theweatherchannel.com/data/




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

http://api.theweatherchannel.com/data/df/SW1P?doctype=xml&country=UK&locale=en_GB&units=m&apikey=c1a56a7d-e149-41ad-9ddb&day=0,1,2,3,4

http://api.theweatherchannel.com/data/df/SW1P?doctype=xml&country=UK&locale=en_GB&units=m&apikey=c1a56a7d-e149-41ad-9ddb&day=0,1,2,3,4

http://api.theweatherchannel.com/image/




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




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",


"snwAccumPhrase":"",

"weatherCode":"3200"},

"night":{"humid":64,

"wSpeed":6,

"wDir":299,

"pop":0,

"uv":0,

"icon":31,

"wDirText":"WNW",

"phrase":"Clear",

"bluntPhrase":"Clear",


http://api.theweatherchannel.com/image/NatlDplr-Md?doctype=img&apikey=c1a56a7d-e149-41ad-9ddb

http://api.theweatherchannel.com/image/NatlDplr-Md?doctype=img&apikey=c1a56a7d-e149-41ad-9ddb

http://api.theweatherchannel.com/data/df/ASXX0112?doctype=json&cb=my_foo&apikey=c1a56a7d-e149-41ad-9ddb

http://api.theweatherchannel.com/data/df/ASXX0112?doctype=json&cb=my_foo&apikey=c1a56a7d-e149-41ad-9ddb




"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




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 ]


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





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

http://api.theweatherchannel.com/data/df/USGA0028?doctype=xml

http://api.theweatherchannel.com/data/df/SW1P?doctype=xml&country=UK

http://api.theweatherchannel.com/data/df/USGA0028?doctype=json

http://api.theweatherchannel.com/data/df/sw1p?doctype=json&country=UK




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

http://api.theweatherchannel.com/data/df/USGA0028?doctype=xml&day=0

http://api.theweatherchannel.com/data/df/sw1p?doctype=xml&country=UK&day=0

http://api.theweatherchannel.com/data/df/sw1p?doctype=xml&country=UK&day=0

http://api.theweatherchannel.com/data/df/USGA0028?doctype=xml&day=0,1,2,3,4

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&day=0,1,2,3,4

http://api.theweatherchannel.com/data/df/sw1p?doctype=xml&country=UK&day=0,1,2,3,4




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>


<phrase>Clear</phrase>

<bluntPhrase>Clear</bluntPhrase>

<precip_type>rain</precip_type>

<snwAccumPhrase/>


</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.




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:


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>


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

http://api.theweatherchannel.com/data/dn/USGA0028?doctype=xml

http://api.theweatherchannel.com/data/dn/sw1p?doctype=xml&country=UK

http://api.theweatherchannel.com/data/dn/USGA0028?doctype=json

http://api.theweatherchannel.com/data/dn/USGA0028?doctype=json&cb=my_foo

http://api.theweatherchannel.com/data/dn/USGA0028?doctype=json&cb=my_foo

http://api.theweatherchannel.com/data/dn/sw1p?doctype=json&country=UK

http://api.theweatherchannel.com/data/dn/sw1p?doctype=json&country=UK&cb=my_foo

http://api.theweatherchannel.com/data/dn/sw1p?doctype=json&country=UK&cb=my_foo




<icon>11</icon>


</narrativeForecast>

<narrativeForecast key="03779000">

<class>narrativeForecast</class>


<dayPart>Tonight</dayPart>

<phrase>Generally clear. Low 52F. Winds WSW at 10 to 15 mph.</phrase>

<uv/>

<icon>31</icon>


</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

http://api.theweatherchannel.com/data/svr/USGA0028?doctype=xml

http://api.theweatherchannel.com/data/svr/30339?doctype=xml

http://api.theweatherchannel.com/data/svr/USGA0028?doctype=json

http://api.theweatherchannel.com/data/svr/USGA0028?doctype=json&cb=my_foo

http://api.theweatherchannel.com/data/svr/USGA0028?doctype=json&cb=my_foo

http://api.theweatherchannel.com/data/svr/30339?doctype=json

http://api.theweatherchannel.com/data/svr/30339?doctype=json&cb=my_foo




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

http://api.theweatherchannel.com/data/trupoint_cc/USGA0028?doctype=xml

http://api.theweatherchannel.com/data/trupoint_cc/sw1p?doctype=xml&country=UK

http://api.theweatherchannel.com/data/trupoint_cc/USGA0028?doctype=json

http://api.theweatherchannel.com/data/trupoint_cc/USGA0028?doctype=json&cb=my_foo

http://api.theweatherchannel.com/data/trupoint_cc/USGA0028?doctype=json&cb=my_foo

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

http://api.theweatherchannel.com/data/trupoint_cc/USGA0028?doctype=json&country=UK&cb=my_foo




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>


<text>Partly Cloudy</text>

<qualifier><![CDATA[Seasonal temperatures.]]></qualifier>

<blunt_phrase><![CDATA[Seasonal temperatures.]]></blunt_phrase>

<terse_phrase><![CDATA[Seasonal temperatures.]]></terse_phrase>

</observation>




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

http://api.theweatherchannel.com/data/loc/USGA0026?doctype=xml


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_foo

http://api.theweatherchannel.com/data/loc/SW1P?doctype=json&country=UK&cb=my_foo

http://api.theweatherchannel.com/data/loc/30339?doctype=xml&country=US


http://api.theweatherchannel.com/data/loc/04758?doctype=xml&country=GM

http://api.theweatherchannel.com/data/loc/75000?doctype=xml&country=FR




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


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




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



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">


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


<obsID>EGLC</obsID>

<dma />

<rgn4 />

<rgn9 />

<zip>SW99</zip>

<parentLoc />

</location>

http://api.theweatherchannel.com/data/locsearch/london?doctype=json

http://api.theweatherchannel.com/data/locsearch/london?doctype=json&cb=my_foo




<location key="CAXX0255" type="1" countryCode="CA" score="0.99999994">


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


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


days The number of days to return [1..5]

The “&days=” parameter will be used to specify how many forecast days to return,

http://api.theweatherchannel.com/data/ss/USGA0028?doctype=xml&days=5

http://api.theweatherchannel.com/data/ss/sw1p?doctype=xml&country=UK&days=5

http://api.theweatherchannel.com/data/ss/USGA0028?doctype=json&days=5

http://api.theweatherchannel.com/data/ss/USGA0028?doctype=json&days=5&cb=my_foo

http://api.theweatherchannel.com/data/ss/USGA0028?doctype=json&days=5&cb=my_foo

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

http://api.theweatherchannel.com/data/ss/USGA0028?doctype=json&country=UK&days=5&cb=my_foo




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)


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




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:


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))


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

http://api.theweatherchannel.com/data/avg/USGA0028?doctype=xml&start=1293840000&end=1296518399

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=1293840000&end=1296518399

http://api.theweatherchannel.com/data/avg/sw1p?doctype=xml&country=UK&start=1293840000&end=1296518399

http://api.theweatherchannel.com/data/avg/USGA0028?doctype=json&start=1293840000&end=1296518399

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=1293840000&end=1296518399

http://api.theweatherchannel.com/data/avg/sw1p?doctype=json&country=UK&start=1293840000&end=1296518399

http://api.theweatherchannel.com/data/avg/USGA0028?doctype=json&cb=my_foo&start=1293840000&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

http://api.theweatherchannel.com/data/avg/sw1p?doctype=json&cb=my_foo&country=UK&start=1293840000&end=1296518399




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>


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




Example of Medium Map:

Example of Large Map:




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}

http://api.theweatherchannel.com/image/NatlHigh-Sm?doctype=img&apikey=%7bAPI_Key%7d

http://api.theweatherchannel.com/image/NatlLow-Sm?doctype=img&apikey=%7bAPI_Key%7d

http://api.theweatherchannel.com/image/NatlPrecip-Sm?doctype=img&apikey=%7bAPI_Key%7d




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}

http://api.theweatherchannel.com/image/NatlDplr-Sm?doctype=img&apikey=%7bAPI_Key%7d

http://api.theweatherchannel.com/image/SeHigh-Sm?doctype=img&apikey=%7bAPI_Key%7d

http://api.theweatherchannel.com/image/SeLow-Sm?doctype=img&apikey=%7bAPI_Key%7d




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}

http://api.theweatherchannel.com/image/SePrecip-Sm?doctype=img&apikey=%7bAPI_Key%7d

http://api.theweatherchannel.com/image/SeDplr-Sm?doctype=img&apikey=%7bAPI_Key%7d

http://api.theweatherchannel.com/imageAkDplr-Sm?doctype=img&apikey=%7bAPI_Key%7d




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}

http://api.theweatherchannel.com/image/HiDplr-Sm?doctype=img&apikey=%7bAPI_Key%7d

http://api.theweatherchannel.com/image/PrDplr-Sm?doctype=img&apikey=%7bAPI_Key%7d

the weather channel® api implementation guide...the weather channel® api implementation guide the...

Documents