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