Weather Company Data API Common Usage Guide

Overview

This common usage and style guide describes the common elements, error handling, language support and terminology used by the Weather Company Data APIs.

HTTP Headers

The following HTTP headers should be set to the appropriate values:

Table 1. HTTP headers
Header Documentation Usage
Accept-Encoding: gzip *http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3 REQUIRED: All requests to the API’s should request that the response be compressed. Unless noted otherwise; the only supported encoding format is: gzip

HTTPS Access

All TWC® APIs support HTTPS. HTTPS is required to be used for all requests to the APIs.

Data Lifetime - Caching and Expiration

  • Standard HTTP Cache-Control headers are used to define caching length. The TTL (Time To Live) value is provided in the HTTP Header as an absolute time value using the “max-age” directive.

Example: “cache-control: max-age=599”.

  • The response may also provide a data element ‘expirationTimeUtc’ or ‘Expires’ which can be used to expire and remove a record from your system.

Cross-Origin Resource Sharing

All TWC APIs support Cross-Origin Resource Sharing or CORS. For additional information on this communications mechanism, please refer to the following documents:

Table 2. Cross-Origin Resource Sharing
Resource Documentation
W3 CORS Specification http://www.w3.org/TR/cors/
CORS Tutorial http://www.html5rocks.com/en/tutorials/cors/

URL Path Components

Table 3. URL Path Components
URL Part URL Part Type Description
hostname host api.weather.com is the host for these API’s
version Path Part Current® API version (example: "v2")
product Path Part Product name (example: “observations/current”)
apiKey Query Parameter Your API key for accessing the API
format Query Parameter The format of the response (“json”)
geocode Query Parameter For API’s which require a location for the data, the geocode is listed in order of latitude and longitude (ex. 34.53,-84.50)
language Query Parameter Language to return the response in (ex. en-US, es, es-MX, fr-FR)
units Query Parameter
  • e = English units
  • m = Metric units
  • h = Hybrid units (UK)
  • s = Metric SI units

HTTP Error Status Codes

There are some differences in error status codes between v1 and v2/v3 APIs; the difference in HTTP status codes is noted in the table below for v1 APIs and v2/v3 APIs.

Table 4. HTTP Error Status Codes v1
v1 API - HTTP Status Code Description
200 OK. The request has succeeded.
400® Bad request. The request could not be understood by the server due to malformed syntax or there is no data found for the location requested.
401 Unauthorized. The request requires authentication.
403 Forbidden. The server understood the request but is refusing to fulfill it.
404 Not found. The endpoint requested is not found.
500 Internal server error. The server encountered an unexpected condition which prevented it from fulfilling the request.
Table 5. HTTP Error Status Codes v2/v3
v2/v3 API - HTTP Status Code Description
204 No Data Found for specific query. The 204 status code will have an empty response body.
400 Bad request. The request could not be understood by the server due to malformed syntax. This is implemented for all API’s. API will reject the request if any invalid parameters are supplied.
401 Unauthorized. The request requires authentication.
403 Forbidden. The server understood the request but the API key is not authorized to perform the requested operation.
404 Not found. The endpoint requested is not found.
405 Method Not Allowed. For example, sending a POST instead of a GET.
406 Not Acceptable. For example, not accepting gzip compressed responses.
408 Request Timeout. Client did not produce a request within the time server was willing to wait.
500 Internal server error. The server encountered an unexpected condition which prevented it from fulfilling the request.
502-504 Service Unavailable or Gateway issue. These error codes are returned if the service is temporarily unavailable.

Standard Units of Measure

Data attributes that respond to the ‘units’ parameter follow the pattern below for the different units of measure applied to the data. The following applies to the majority of APIs. Please refer to respective API documentation for possible deviations.

Table 6. Standard Units of Measure
Long Name Imperial (English) - e Metric - m Metric SI - s Hybrid UK - h
Altitude ft (feet) m (meters) m (meters) ft (feet)
Temperature f (fahrenheit) c (celsius) c (celsius) c (celsius)
Pressure hg (inches of mercury) mb (millibars of mercury) mb (millibars of mercury) mb (millibars)
Precipitation Amount in (inches) - rain/snow

mm (millimeters - rain),

cm (centimeters - snow)

mm (millimeters - rain),

cm (centimeters - snow)

mm (millimeters - rain),

cm (centimeters - snow)

Distance mi (miles) km (kilometer) m (meter) mi (miles)
Visibility mi (miles) km (kilometer) km (kilometer) km (kilometer)
Wind Speed mh (miles/hour) km (kilometer/hour) m/s (meters per second) mph (miles per hour)
Wave Height ft (feet) mtr (meter) ft (feet)  

Unit of Measure Conversion Tables

Table 7. Units of Measure Conversion Tables
Type Imperial to Metric Metric to Imperial
Temperature Fahrenheit to Celsius: Divide (F - 32) by 1.8 Celsius to Fahrenheit: Multiply C by 1.8 and Add 32
Pressure Inches of Mercury to Millibars: Multiply Inches by 33.8637526 Millibars to Inches of Mercury : Multiply Millibars by 0.0295301
Distance/Speed Imperial to Metric Metric to Imperial
Miles to Kilometers: Multiply Miles by 1.60934 Kilometers to Miles : Multiply Kilometers by 0.6214  
Feet to Meters: Multiply Feet By 0.3048 Meters to Feet: Multiply Meters By 3.2808  
Miles per Hour (MPH) to Meters Per Second: Multiply MPH by 0.44704 Meters Per Second(M/S) to Miles per Hour: Multiply M/S by 2.2369362920544  
Inches to Centimeters: Multiply Inches by 2.54 Centimeters to Inches: Multiply Centimeters by 0.39370  
Inches to Millimeters: Multiply Inches by 25.4 Millimeters to Inches: Multiply Centimeters by 0.0393701  
Metric Conversions    

Kilometer per Hour (KPH) to Meters Per Second: Multiply KPH by 0.277778

Meters Per Second (M/S)to Kilometer per Hour: Multiply M/S by 3.6

   

Postal Code and Postal Key Support

Some APIs support requests by postal code. There is limited postal code support for v1 APIs. If a v1 API is noted with postal code support; the following countries postal codes are supported. Further, v3 APIs support requests by postal KEY. Postal Key will always be represented in a query in the camelCase format of ‘postalKey’ and will be formatted as ‘postalCode:countryCode’, i.e.: ‘postalKey=81657:US’.

Supported countries for v1 postal codes are listed below:

Table 8. Postal Code and Postal Key Support

United States

Country Code: US

United Kingdom

Country Code: GB

France

Country Code: FR

Germany

Country Code: DE

Italy

Country Code: IT

Supported countries for v3 postalKeys are listed below:

Table 9. Supported countries for v3 postalKeys

Andorra

Country Code: AD

Afghanistan

Country Code: AF

Anguilla

Country Code: AI

Albania

Country Code: AL

Armenia

Country Code: AM

Supports first 2 digits (out of 4)

Argentina

Country Code: AR

Supports 5 alphanumeric character precision (out of 8)

American Samoa

Country Code: AS

Austria

Country Code: AT

Australia

Country Code: AU

Azerbaijan

Country Code: AZ

Supports Regional (First 2 Digits)

Bosnia and Herzegovina

Country Code: BA

Bangladesh

Country Code: BD

Supports first 2 digits (out of 4)

Belgium

Country Code: BE

Bulgaria

Country Code: BG

Bahrain

Country Code: BH

Saint Barthélemy

Country Code: BL

Bermuda

Country Code: BM

Nation of Brunei

Country Code: BN

Supports first 2 characters (district level)

Brazil

Country Code: BR

Bhutan

Country Code: BT

Supports first 2 digits

Belarus

Country Code: BY

Canada

Country Code: CA

Support only the first 3 postal code characters (out of 6)

Cocos Islands

Country Code: CC

Switzerland

Country Code: CH

Chile

Country Code: CL

Support regional codes - first 3 characters (out of 7)

People’s Republic of China

Country Code: CN

Supports first 4 digits

Colombia

Country Code: CO

Supports first 4 digits

Costa Rica

Country Code: CR

Cape Verde

Country Code: CV

Christmas Island

Country Code: CX

Cyprus

Country Code: CY

Czech Republic

Country Code: CZ

Germany

Country Code: DE

Denmark

Country Code: DK

Dominican Republic

Country Code: DO

Algeria

Country Code: DZ

Ecuador

Country Code: EC

Estonia

Country Code: EE

Egypt

Country Code: EG

Support only the first 2 characters (out of 5)

Spain

Country Code: ES

Finland

Country Code: FI

Federated States of Micronesia

Country Code: FM

Faroe Islands

Country Code: FO

France

Country Code: FR

United Kingdom

Country Code: GB

Support Outward code and Sector ('XX X' or 'XXX X' or 'XXXX X')

Georgia

Country Code: GE

Supports first 2 digits

French Guiana

Country Code: GF

Guernsey

Country Code: GG

Ghana

Country Code: GH

Supports first 2 characters

Gibraltar

Country Code: GI

Greenland

Country Code: GL

Guadeloupe

Country Code: GP

Greece

Country Code: GR

South Georgia and the South Sandwich Islands

Country Code: GS

Guatemala

Country Code: GT

Guam

Country Code: GU

Guinea-Bissau

Country Code: GW

Honduras

Country Code: HN

Supports first 2 digits

Croatia

Country Code: HR

Haiti

Country Code: HT

Hungary

Country Code: HU

Indonesia

Country Code: ID

Ireland

Country Code: IE

Supports first 3 characters

Israel

Country Code: IL

Supports first 5 digits (out of 7)

Isle of Man

Country Code: IM

Support Outward code and Sector ('XX X' or 'XXX X' or 'XXXX X')

India

Country Code: IN

British Indian OOcean Territory

Country Code: IO

Iraq

Country Code: IQ

Supports first 2 digits (out of 5)

Iran

Country Code: IR

Supports first 2 digits (out of 5)

Iceland

Country Code: IS

Italy

Country Code: IT

Jersey

Country Code: JE

Support Outward code and Sector ('XX X' or 'XXX X' or 'XXXX X')

Jordan

Country Code: JO

Japan

Country Code: JP

Kenya

Country Code: KE

Support only the first character (out of 6)

Kyrgyzstan

Country Code: KG

Supports first 4 digits

Cambodia

Country Code: KH

Supports first 2 digits

South Korea

Country Code: KR

Kuwait

Country Code: KW

Supports first 2 digits

Cayman Islands

Country Code: KY

Kazakhstan

Country Code: KZ

Supports first 4 digits

Laos

Country Code: LA

Supports first 2 digits

Saint Lucia

Country Code: LC

Liechtenstein

Country Code: LI

Sri Lanka

Country Code: LK

Supports first 2 digits

Liberia

Country Code: LR

Supports first 2 digits

Lesotho

Country Code: LS

Supports first digit

Lithuania

Country Code: LT

Luxembourg

Country Code: LU

Latvia

Country Code: LV

Morocco

Country Code: MA

Monaco

Country Code: MC

Moldova

Country Code: MD

Montenegro

Country Code: ME

Saint Martin

Country Code: MF

Madagascar

Country Code: MG

Marshall Islands

Country Code: MH

Supports first 3 digits (out of 5)

The Republic of North Macedonia

Country Code: MK

Myanmar

Country Code: MM

Supports first 2 digits

Mongolia

Country Code: MN

Supports first 4 digits

Northern Mariana Islands

Country Code: MP

Martinique

Country Code: MQ

Montserrat

Country Code: MS

Malta

Country Code: MT

Support only first 3 characters (out of 7)

Mauritius

Country Code: MU

Supports first 3 digits (out of 5)

Maldives

Country Code: MV

Supports first 2 digits

Mexico

Country Code: MX

Malaysia

Country Code: MY

Mozambique

Country Code: MZ

New Caledonia

Country Code: NC

Niger

Country Code: NE

Norfolk Island

Country Code: NF

Nigeria

Country Code: NG

Supports first 4 digits

Nicaragua

Country Code: NI

Supports first 3 digits

Netherlands

Country Code: NL

Namibia

Country Code: NM

Norway

Country Code: NO

Nepal

Country Code: NP

Supports first 3 digits (out of 5)

New Zealand

Country Code: NZ

Oman

Country Code: OM

Supports first digit

Peru

Country Code: PE

French Polynesia

Country Code: PF

Papua New Guinea

Country Code: PG

Philippines

Country Code: PH

Pakistan

Country Code: PK

Supports first 2 digits

Poland

Country Code: PL

Saint Pierre and Miquelon

Country Code: PM

Puerto Rico

Country Code: PR

Palestine

Country Code: PS

Portugal

Country Code: PT

Palau

Country Code: PW

Paraguay

Country Code: PY

Supports first digit

Réunion

Country Code: RE

Romania

Country Code: RO

Serbia

Country Code: RS

Russia

Country Code: RU

Support first 4 characters (out of 6)

Saudi Arabia

Country Code: SA

Supports first 2 digits

Sudan

Country Code: SD

Supports first 2 digits

Sweden

Country Code: SE

Singapore

Country Code: SG

Supports first 2 characters (out of 6)

Slovenia

Country Code: SI

Svalbard and Jan Mayen

Country Code: SJ

Slovakia

Country Code: SK

San Marino

Country Code: SM

Senegal

Country Code: SN

South Sudan

Country Code: SS

El Salvador

Country Code: SV

Eswatini

Country Code: SZ

Supports first character

Turks and Caicos Islands

Country Code: TC

Thailand

Country Code: TH

Tajikistan

Country Code: TJ

Supports first 4 digits

Turkmenistan

Country Code: TM

Supports first 3 digits

Tunisia

Country Code: TN

Turkey

Country Code: TR

Trinidad and Tobago

Country Code: TT

Supports first 2 digits

Taiwan

Country Code: TW

Supports first 3 digits

Tanzania

Country Code: TZ

Supports first 3 characters (out of 5)

Ukraine

Country Code: UA

United States

Country Code: US

Uruguay

Country Code: UY

Uzbekistan

Country Code: UZ

Supports first 4 digits

Vatican City

Country Code: VA

Saint Vincent and the Grenadines

Country Code: VC

Supports first 4 characters

Venezuela

Country Code: VE

British Virgin Islands

Country Code: VG

United States Virgin Islands

Country Code: VI

Vietnam

Country Code: VN

Wallis and Futuna

Country Code: WF

Samoa

Country Code: WS

Supports first 3 characters (out of 6)

Kosovo

Country Code: XK

Supports first 2 digits

Mayotte

Country Code: YT

South Africa

Country Code: ZA

Zambia

Country Code: ZM

     

Language Translations & Language Codes

Some attributes support language translations. Any attribute that supports translated content will be noted as such in the ‘Translated Fields’ section of the API specific documentation. The ‘Translated Fields’ section denotes which fields respond to the valid ‘language’ parameter in the API request. Translated content will only be provided for valid supported languages as noted in the Language Code table.

Table 10. Language Translations & Language Codes
am-ET Amharic - (Ethiopia) hi-IN Hindi - (India) pt-BR Portuguese - (Brazil)
ar-AE Arabic - (United Arab Emirates) hr-HR Croatian - (Croatia) pt-PT Portuguese - (Portugal)
az-AZ Azerbaijani - (Azerbaijan) hu-HU Hungarian - (Hungary) ro-RO Romanian - (Romania)
bg-BG Bulgarian - (Bulgaria) id-ID Indonesian - (Indonesia) ru-RU Russian - (Russia)
bn-BD Bengali, Bangla - (Bangladesh) is-IS Icelandic - (Iceland) si-LK Sinhalese, Sinhala - (Sri Lanka)
bn-IN Bengali, Bangla - (India) it-IT Italian - (Italy) sk-SK Slovak - (Slovakia)
bs-BA Bosnian - (Bosnia and Herzegovina) iw-IL Hebrew - (Israel) sl-SI Slovenian - (Slovenia)
ca-ES Catalan - (Spain) ja-JP Japanese - (Japan) sq-AL Albanian - (Albania)
cs-CZ Czech - (Czechia) jv-ID Javanese - (Indonesia) sr-BA Serbian - (Bosnia and Herzegovina)
da-DK Danish - (Denmark) ka-GE Georgian - (Georgia) sr-ME Serbian - (Montenegro)
de-DE German - (Germany) kk-KZ Kazakh - (Kazakhstan) sr-RS Serbian - (Serbia)
el-GR Greek (modern) - (Greece) km-KH Khmer - (Cambodia) sv-SE Swedish - (Sweden)
en-CA English - (Canada) kn-IN Kannada - (India) sw-KE Swahili - (Kenya)
en-GB English - (Great Britain) ko-KR Korean - (South Korea) ta-IN Tamil - (India)
en-IN English - (India) lo-LA Lao - (Laos) ta-LK Tamil - (Sri Lanka)
en-US English - (United States of America) lt-LT Lithuanian - (Lithuania) te-IN Telugu - (India)
en-AI English - (Australia) lv-LV Latvian - (Latvia) ti-ER Tigrinya - (Eritrea)
es-AR Spanish - (Argentina) mk-MK Macedonian - (Macedonia) ti-ET Tigrinya - (Ethiopia)
es-ES Spanish - (Spain) mn-MN Mongolian - (Mongolia) tg-TJ Tajik - (Tajikistan)
es-LA Spanish - (Latin America) mr-IN Marathi - (India) th-TH Thai - (Thailand)
es-MX Spanish - (Mexico) ms-MY Malay - (Malaysia) tk-TM Turkmen - (Turkmenistan)
es-UN Spanish - (International) my-MM Burmese - (Myanmar) tl-PH Tagalog - (Philippines)
es-US Spanish - (United States of America) ne-IN Nepali - (India) tr-TR Turkish - (Turkey)
et-EE Estonian - (Estonia) ne-NP Nepali - (Nepal) uk-UA Ukrainian - (Ukraine)
fa-IR Persian (Farsi) - (Iran) nl-NL Dutch - (Netherlands) ur-PK Urdu - (Pakistan)
fi-FI Finnish - (Finland) no-NO Norwegian - (Norway) uz-UZ Uzbek - (Uzbekistan)
fr-CA French - (Canada) om-ET Oromo - (Ethiopia) vi-VN Vietnamese - (Viet Nam)
fr-FR French - (France) pa-IN Punjabi - (India) zh-CN Chinese - (China)
gu-IN Gujarati - (India) pa-PK Punjabi - (Pakistan) zh-HK Chinese - (Hong Kong)
he-IL Hebrew (modern) - (Israel) pl-PL Polish - (Poland) zh-TW Chinese - (Taiwan)