Location Service - Search

Overview

Domain Portfolio: Utility
Domain: Search
Usage Classification: Standard
Geography: Global
Attribution Required: N/A
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 Search API provides the ability to pass location search input parameters from users, applications or other systems and retrieve a set of location responses that best align with the query string provided. This API will return a list of up to 10 locations, sorted by priority, based on the query parameters provided.

The Location Search API is most commonly used for typeahead search user interfaces or voice assistant queries where users request a named location to identify its geographic coordinates and other related metadata.

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
Request by	Aggregate Product Name
City Name: Required Parameters: query, language, format \|\|Optional Parameters: countryCode, adminDistrictCode, locationType, proximity, fuzzyMatch Returns information in an array for the string included in the query= parameter. The optional parameters further refine the search response. https://api.weather.com/v3/location/search?query=atlanta&language=en-US&format=json&apiKey=yourApiKey https://api.weather.com/v3/location/search?query=Lincoln Memorial Circle SW&locationType=address&language=en-US&format=json&apiKey=yourApiKey	v3-location-search

Optional Query Parameters

Table 2. Optional Query Parameters
Parameter Name	Description	Type	Range	Sample
countryCode	Specify the query string results to the provided country code.	string	Any valid ISO 3166 alpha 2 code.	US
adminDistrictCode	Filter the response to return only locations within the admin district code specified.	string	Any valid state code in the United States.	GA
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
proximity	Specify whether the search results should be biased to return results closer to the latitude,longitude location provided.	geocode	Any valid latitude longitude pair.	33.43,-84.32
fuzzyMatch	Specify whether the database should attempt approximate and/or exact matching to the query string provided in the request. true = attempt approximate and exact matching false = attempt exact matching only Note: requests without this query parameter default the value to ‘true’	boolean	true or false	true

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

Table 4. Data Elements and Definitions
Field Name	Description	Type	Range	Sample	Nulls Allowed
location	Object for location data	object
address	Locale level location detail.	[string]		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.	[string]	Any valid airport name.	Hartsfield-Jackson Intl,	Y
city	Full name of location City	string	Any valid city name.	Atlanta,	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	false,true	Y
ianaTimeZone	The standard IANA Time Zone for the location requested.	[string]	Any valid IANA time zone.	America/New_York,	Y
icaoCode	4-digit airport code.	[string]	Any valid icaoCode	KATL	Y
iataCode	3-digit airport code.	[string]	Any valid iataCode	ATL	Y
latitude	Center latitude coordinate of the requested location.	[decimal]	Any valid latitude value.	33.638271,	N
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
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
longitude	Center longitude coordinate of the requested location.	[decimal]	Any valid longitude value.	-84.429369,	N
neighborhood	The recognized Neighborhood name of the requested location.	[string]	Any valid neighborhood name.	Eagan Park,	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
placeId	A unique place identifier	[string]	Unique Place Identifier	25d07eca1bcda02800c1a9e699d7eb1c8132cad9bc2d6efa8a2531f0ee4a81cd	N
pwsId	Personal Weather Station identifier	[string]	Any valid pwsId	KTXSANMA13	Y
type	Geospatial definition for the location record. (location type).	[string]	Any valid type	city, address, poi	N
locale	Object for additional city and sub-city locale information	[array]
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 - Search

// Response Collapsed for Presentation Purposes
{
                     location: {
                                   address: ["Atlanta, Georgia, United States"],
                                   adminDistrict: ["Georgia"], 
                                   adminDistrictCode: ["GA"],
                                   city: ["Atlanta"],
                                   country: ["United States"],
                                   countryCode: ["US"],
                                   displayName: ["Atlanta"],
                                   ianaTimeZone: ["America/New_York"],
                                   latitude: [33.749],
                                   locale: [{locale1: null,locale2: "Atlanta",locale3: null,locale4: null},],
                                   longitude: [-84.39],
                                   neighborhood: [null],
                                   placeId: ["8f5c8f0c5dd7699966caf7dcb4880c3847a86092521a187546b808f3023b9120"],
                                   postalCode: ["30303"],
                                   postalKey: ["30303:US"],
                                   iataCode: [“ATL”],
                                   icaoCode: [“KATL”],
                                   disputedArea: [false],
                                   disputedCountries: [null],
                                   disputedCountryCodes: [null],
                                   disputedCustomers: [null],
                                   disputedShowCountry: [[false]],
                                   locId: [null],
                                   locationCategory: [null],
                                   pwsId: [null],
                                   type: ["city"]
                    }
}