Location Service - Point

Overview

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

The Location Service APIs provide the ability to lookup a location name or geocode (latitude and longitude) to retrieve a set of locations matching the request.

The Location Point API provides detailed location data for a specific point on the globe, searchable by: Geocode (Latitude and Longitude), Postal Key (postal code:country code composite), IATA Code, ICAO Code, Place ID (encrypted location identifier), Canonical City ID (city level feature identifier), and Location ID (legacy location identifier).

The Location Point API is most commonly used for GPS based location searches where a pair of coordinates or known location codes are queried to identify its location features and other related metadata.

Note: Points over a body of water will generate a 404 error.

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.

Translated Fields:

This TWC® API handles the translation of phrases. However, when formatting a request URL a valid language must be passed along (see the language code table for the supported codes).
  • address
  • adminDistrict
  • country

URL Construction

Table 1. URL construction
Search by Aggregate Product Name

Geocode

Required Parameters: geocode, language, format || Optional Parameters: locationType

Returns information for a search via a latitude,longitude pair like “33.43,-84.22”.

https://api.weather.com/v3/location/point?geocode=33.74,-84.39&language=en-US&format=json&apiKey=yourApiKey
v3-location-point

Postal Key

Required Parameters: postalKey, language, format || Optional Parameters: locationType

Returns information for search via a Postal Key like “30339:US”. A Postal Key is a composite of <Postal Code>:<Country Code>.

https://api.weather.com/v3/location/point?postalKey=30339:US&language=en-US&format=json&apiKey=yourApiKey
v3-location-point

IATA Code [location/point only]

Required Parameters: iataCode, language, format

Returns information for search via an IATA code like “ATL”.

https://api.weather.com/v3/location/point?iataCode=ATL&language=en-US&format=json&apiKey=yourApiKey
v3-location-point

ICAO Code [location/point only]

Required Parameters: icaoCode, language, format

Returns information for search via an ICAO code like “KATL”.

https://api.weather.com/v3/location/point?icaoCode=KATL&language=en-US&format=json&apiKey=yourApiKey
v3-location-point

Place ID

Required Parameters: placeid, language, format

Returns information for search via a Place ID like “ee0214ae7fb1d265f3e4d2509e77557119b2cac9d0ac1013b593c74a1567f2b7”

https://api.weather.com/v3/location/point?placeid=ee0214ae7fb1d265f3e4d2509e77557119b2cac9d0ac1013b593c74a1567f2b7&language=en-US&format=json&apiKey=yourApiKey
v3-location-point

Canonical City ID

Required Parameters: locid, language, format

Returns information for search via a Canonical City ID like “3e933388e3fb38c28c2d0806165bf7e3185d84bbb370417734798573ee243240”.

https://api.weather.com/v3/location/point?canonicalCityId=3e933388e3fb38c28c2d0806165bf7e3185d84bbb370417734798573ee243240&language=en-US&format=json&apiKey=yourApiKey
v3-location-point

Location ID

Required Parameters: locid, language, format

Returns information for search via a Location ID like “USWY0183:1:US”. This method of request is no longer actively supported.

https://api.weather.com/v3/location/point?locid=USWY0183:1:US&language=en-US&format=json&apiKey=yourApiKey
v3-location-point

Optional Query Parameters

Table 2. Optional Query Parameters
Parameter Name Description Type Range
locationType

Specify what type of location should be returned in the request. This determines the level of granularity expected in the response. Multiple location types may be requested as comma separated values in one request.

Note: it is recommended to limit the types requested for best results

See more details in the Location Types section.

city, locality, neighborhood, state, address, poi, pws, country, postal, locale (includes city, locality, and neighborhood), locid (not actively supported) city,locality,neighborhood

Location Types

Table 3. Location types
Types Description
country Features that have been given a designated country code under ISO 3166-1.
state Top-level sub-national administrative features. ‘region’ is a comparable type as ‘state’.
district Features that are smaller than states/regions but larger than cities.
city Features generally recognized as cities, villages, municipalities, etc. Typically locations used in postal addressing. Most commonly used for end-user location presentation.
locality Official sub-city features used in postal addressing or commonly known to local residents.
neighborhood Colloquial sub-city features which often lack official administrative status and lack agreed-upon boundaries.
locale A location type sub-grouping combining city, locality, and neighborhood features. This type has been made obsolete by the ability to request multiple location types via a comma separated list.
postal Postal codes used in country-specific national addressing systems.
address Individual residential or business addresses.
poi Points of Interest.
airport Valid, active airports. Curated internally by The Weather Company, an IBM® Business.
pws Valid, active Personal Weather Stations. Curated internally by The Weather Company, an IBM Business.
locid Legacy location identifiers. Curated internally by The Weather Company, an IBM Business. This location type is no longer actively supported.

Data Elements & Definitions - Location Service - Point

Table 4. Data Elements and Definitions - Location Service - Point
Field Name Description Type Range Sample Null Allowed
location Object for location data object      
address Locale level location detail.   Atlanta, Georgia, United States   Y
adminDistrict

The internationalized State, Region, District or Province identifier for ‘state’ or geopolitical area.

- level 1 administrative division.

string Any valid state, region, district or province name. Georgia, Y
adminDistrictCode

The identifier code for ‘state’ or geopolitical area.

- level 1 administrative division.

string US states only. GA, Y
airportName

The airport name associated to the (ICAO / IATA) airport code.

Note: Only returned when the iataCode or ianaCode query parameter is used in the request.

string Any valid airport name. Hartsfield-Jackson Intl, Y
canonicalCityId

A city level place identifier. The canonical city id encompasses lower level place types.

Note: This value should be used for SEO purposes only.

string Any valid canonicalCityId b9561b6ddb213b878ba672863570cf55d936ecb80cacd7fe8c45fe9379288343 Y
city Full name of location City string Any valid city name. Atlanta, Y
countyId Governmental assigned county identifier. Internal use only string Any valid County ID FLC117, Y
country Full name of location Country string Any valid country name. United States, Y
countryCode ISO Country Code string Any valid ISO country code. US, Y
displayName The common display name for a location. string Any valid location display name. Atlanta, Y
disputedArea Point falls in an area with political sensitivity. boolean true, false false, Y
disputedCountries

List of countries claiming territory in the provided disputedArea.

Note: Currently only available for disputedAreas with India, Israel, South Korea, Taiwan

[string] Any valid country name. [“United States”,”Canada”] Y
disputedCountryCodes List of ISO country codes representing the disputedCountries. [string] Any valid ISO country code. [“US”, “CA”] Y
disputedCustomers Customer identifier for custom logic pertaining to areas with political sensitivity. [array] Any valid internal code. [[“ABC”],[]] Y
disputedShowCountry Customer designation for display of country names. [boolean] true, false [true,false] Y
dmaCd DMA Code. Internal use only. A Designated Market Area (DMA) is a group of counties in the United States that are covered by a specific group of television stations. The term was coined by Nielsen Media Research, and they control the trademark on it. There are 210 DMAs in the United States. string Any valid DMA Code 534 Y
dstEnd The date time which the location ends daylight savings time observation. ISO Any valid ISO date time. 2017-11-05T01:00:00-0500 Y
dstStart The date time which the location starts daylight savings time observation. ISO Any valid ISO date time. 2017-03-12T03:00:00-0400 Y
ianaTimeZone The standard IANA Time Zone for the location requested. string Any valid IANA time zone or UTC offset. America/New_York, Y
iataCode

The International Air Transport Association (IATA) airport codes of the requested location.

Note: Only returned when the iataCode query parameter is used in the request.

string Any valid IATA code. ATL, Y
icaoCode

The International Civil Aviation Organization (ICAO) airport codes of the requested location.

Note: Only returned when the iacoCode query parameter is used in the request.

string Any valid ICAO code. KATL, Y
latitude Center latitude coordinate of the requested location. decimal Any valid latitude value. 33.63, N
locId Legacy TWC location identifier corresponding to a unique location record. This location type is provided to ensure compatibility with legacy queries. string Any valid locId USWY0183:1:US Y
locationCategory A sub-type of the 'type' field that describes a more specific grouping for the location record. Currently returns a non-null response when "type"= "poi". In all other instances, this field will return 'null'. string Any valid locationCategory national park Y
longitude Center longitude coordinate of the requested location. decimal Any valid longitude value. -84.42, N
neighborhood The recognized Neighborhood name of the requested location. string Any valid neighborhood name. Eagan Park, Y
placeId A unique place identifier string Unique Place Identifier 25d07eca1bcda02800c1a9e699d7eb1c8132cad9bc2d6efa8a2531f0ee4a81cd N
pollenId The pollen station identifier. Only valid in the United States. string Any valid pollenId ATL Y
postalCode The Postal Code of the requested location. string Any valid postal code. 30337, Y
postalKey Postal Key is a composite location identifier key of <Postal Code>:<Country Code> string Any valid postal key value. 30337:US, Y
pwsId Personal Weather Station identifier string Any valid pwsId KTXSANMA13, Y
regionalSatellite A TWC defined area that identifies a satellite region on the globe. string Any valid reginal satellite value. se Y
tideId The tide station identifier. Only available for locations near coastlines string Any valid tideId 8729511 Y
type Geospatial definition for the location record. (location type). string Any valid type city, address, poi,neighborhood, state N
zoneId Government assigned location identifier string Any valid zoneId GAZ033, Y
locale Object for additional city & sub-city locale information. object      
locale1 City or Sub-City locale information - depending on country. Broadest area local. (district) string Any valid city or sub-city locale Y
locale2 City or Sub-City locale information - depending on country. 1 level more granular than ‘locale1’ (city) string Any valid city or sub-city locale Y
locale3 City or Sub-City locale information - depending on country. 1 level more granular than ‘locale2’ (locality) string Any valid city or sub-city locale Y
locale4 City or Sub-City locale information - depending on country. Smallest area local. (neighborhood) string Any valid city or sub-city locale Y

JSON Sample - Location Service - Point

// Response Collapsed for Presentation Purposes

{
          location: {
               latitude: 28.756,
               longitude: -81.322,
               city: "Lake Mary",
               locale: {
                             locale1: null,
                             locale2: "Lake Mary",
                             locale3: null,
                             locale4: null
                },
                neighborhood: null,
                adminDistrict: "Florida",
                adminDistrictCode: "FL",
                postalCode: "32746",
                postalKey: "32746:US",
                country: "United States of America",
                countryCode: "US",
                ianaTimeZone: "America/New_York",
                displayName: "Lake Mary",
                dstEnd: "2019-11-03T01:00:00-0500",
                dstStart: "2019-03-10T03:00:00-0400",
                dmaCd: "534",
                placeId: "04e257d440ab656b61dad6432d2009c58aa9ebc939bbdf0262bd21110c90aca0",
                disputedArea: true,
                disputedCountries: null,
                disputedCountryCodes: null,
                disputedCustomers: [[]],
                disputedShowCountry: [false],
                canonicalCityId: "b9561b6ddb213b878ba672863570cf55d936ecb80cacd7fe8c45fe9379288343",     
                countyId: "FLC117",
                locId: null,
                locationCategory: null, 
                pollenId: "ORL",
                pwsId: null,
                regionalSatellite: "se",
                tideId: "8721222",
                type: "city",
                zoneId: "FLZ046"
        }
}