Location Services - Boundary

Overview

  • Domain Portfolio: Utility
  • Domain: Search
  • Usage Classification: Limited Availability
  • Geography: Global
  • Attribution Required: N/A
  • Attribution Requirements: N/A

The Location Service - Boundary API looks up the requested key in the requested product and returns the polygonal geometry as a JSON document. Data returned for all product types will be in the form of a list of boundary coordinates. For this API JSON returned will always be GeoJSON.

Note: Please see the field "product" in the response to validate that the call has been properly made for the intended boundary (county, pollen, postalKey, zone).

HTTP Headers and Data Lifetime - Caching and Expiration

For details on appropriate header values as well as caching and expiration definitions, please see The Weather Company Data | API Common Usage Guide.

Table 1. HTTP headers
URL Construction Aggregate Product Name
   
https://api.weather.com/v3/location/boundary?geocode=33.33,-83.22&product=adminDistrict1&format=json&apiKey=yourApiKey v3-location-boundary

Request by IATA Code: Required Parameters: iataCode, type, product, format

https://api.weather.com/v3/location/boundary?iataCode=<iataCode>&product=<product>&format=<format>&apiKey=<apiKey>

v3-location-boundary
https://api.weather.com/v3/location/boundary?iataCode=FCO&product=adminDistrict1&format=json&apiKey=yourApiKey v3-location-boundary

Request by ICAO Code: Required Parameters: icaoCode, type, product, format

https://api.weather.com/v3/location/boundary?icaoCode=<icaoCode>&product=<product>&format=<format>&apiKey=<apiKey>

v3-location-boundary
https://api.weather.com/v3/location/boundary?icaoCode=LIRF&product=adminDistrict1&format=json&apiKey=yourApiKey v3-location-boundary

Request by Place ID: Required Parameters: placeid, type, product, format

https://api.weather.com/v3/location/boundary?placeid=<placeid>&product=<product>&format=<format>&apiKey=<apiKey>

v3-location-boundary
https://api.weather.com/v3/location/boundary?placeid=25d07eca1bcda02800c1a9e699d7eb1c8132cad9bc2d6efa8a2531f0ee4a81cd&product=adminDistrict1&format=json&apiKey=yourApiKey v3-location-boundary

Request by Postal Key: Required Parameters: postalKey, type, product, format

https://api.weather.com/v3/location/boundary?postalKey=<postalKey>&product=<product>&format=<format>&apiKey=<apiKey>

v3-location-boundary
https://api.weather.com/v3/location/boundary?postalKey=98101:US&product=adminDistrict1&format=json&apiKey=yourApiKey v3-location-boundary

Request by Geocode: Required Parameters: geocode, type, product, format

https://api.weather.com/v3/location/boundary?geocode=<geocode>&product=<product>&format=<format>&apiKey=<apiKey>

v3-location-boundary

Valid Parameters

Parameter Name Valid Parameter Values
type countyId, iataCode, icaoCode, postalKey, zoneId, placeId
product county, pollen, postalKey, zone
Valid Parameter Value for parameter:type (location type identifier) Description
countyId Governmental assigned county identifier
iataCode The International Air Transport Association (IATA) airport codes of the requested location.
icaoCode The International Civil Aviation Organization (ICAO) airport codes of the requested location.
placeId A proprietary TWC unique place identifier.
postalKey Postal Key is a composite location identifier key of <Postal Code>:<Country Code>
zoneId Government assigned zone identifier.
Valid Parameter Value for parameter: product Description
county County name of requested location.
pollen Boundary of area included for pollen observations.
postalKey Postal Key is a composite Postal Code location identifier key of <Postal Code>:<Country Code>
zone Governmental assigned zone.

Valid Parameter Definitions

Parameter Name Description Example
API Key apiKey The “apiKey” is used for access using the api; usually customer specific. ..v3/<product>?apiKey=yourApiKey
Format format The format of the response (json) ..v3/<product>?format=json
Product product The product is the identifier type used in the query. Valid values include; airport, pws, ski.

..v3/<product>?product=adminDistrict1

..v3/<product>?product=almanac

..v3/<product>?product=zone
Location Parameter Name Description Example
Geocode geocode

TWC uses valid latitudes and longitude coordinates to identify locations worldwide. Uses WGS84 geocode coordinate reference system. https://www.w3.org/2003/01/geo/

33.40,83.19 is the manner in which a latitude and longitude is accepted for the weather APIs.

 ..v3/<product>?geocode=34.063,-84.217
IATA Code iataCode

IATA Code = 3 character International Air Transport Association airport codes

IATA (International Air Transport Association) is a trade association that focuses on making air traffic businesses safe, secure, reliable and efficient.

 ..v3/<product>?iataCode=FCO
ICAO Code icaoCode

ICAO Code = 4 character International Civil Aviation Organization airport codes

ICAO (International Civil Aviation Organization) is a UN-body which focuses on international harmonization of civil aviation regulations.

 ..v3/<product>?icaoCode=LIRF
Postal Key postalKey

Postal Key is a composite location identifier key of <Postal Code>:<Country Code>

<Postal Code>:<Country Code>

..v3/<product>?postalKey=30339:US

..v3/<product>?postalKey=75003:FR

..v3/<product>?postalKey=75003:EE

Data Elements & Definitions

Note: Field names are sorted alphabetically in the table below for presentation purposes. The table below does not represent the sort order of the API response.

Field Name Description Type Range Sample Nulls Allowed
type   [array]     N
features   [array]     N
geometry   [array]     N
type Describes the type of coordinates returned in the geometry: object. countyId, geocode, iataCode, icaoCode, locId, postalKey, ski, zone, zoneId string   geocode N
coordinates Array of GeoJSON coordinates ordered as: (longitude, latitude) which defines the polygon geometry. The returned coordinates will represent the boundary of the requested ‘type’ (See list above). [array]     N
properties   [array]     N
product Requested product type identifier. airportName, alerts, city, locality, location, near, products, zoneId string   alerts N
key Product key. For The Weather Company internal usage only. string     N

JSON Sample

// Response Collapsed for Presentation Purposes

{
	type: "FeatureCollection",
	features: [
	{
	           type: "Feature",
	           geometry: {
	                      coordinates: [
	                                  [
	                                      [
	                                              -122.459774,
	                                               47.672418
	                                      ],
	                                      [
	                                              -122.459737,
	                                               47.67212
	                                      ],
	                                      [
	                                              -122.45962,
	                                               47.671118
	                                      ],
	                                      [
	                                              -122.370464,
                                               	47.506398
	                                      ],
                                      	[
	                                              -122.459774,
	                                               47.672418
	                                      ]
	                                      ]
	                 ],
	                 type: "Polygon"
	},
	properties: {
	                 product: "adminDistrict3",
	                 key: "612255"
	            }
	      }
	]
}