Text Search

Learn how to get a global list of cities and locations by using text search.

We'll cover the following

Overview

In this lesson, we learn how to search for locations worldwide by using text search.

Search for global locations

The Text Search endpoint allows us to retrieve a list of all locations around the globe that match our given text. It provides detailed information for each location, including, but not limited to, its geographical position, timezone, and population. We can also limit the number of results retrieved as per our requirements.

For this purpose, we make a GET request to the following URL.

http://dataservice.accuweather.com/locations/v1/search

URL query parameters

Parameter

Type

Category

Description

API_KEY

string

required

This is our API key.

q

string

required

This is the search text.

language

string

optional

This is the language in which we have to return the results.

Its default value is "en-us."

details

boolean

optional

This is set to "True" to include full details in the response, otherwise it is set to "False." 

Its default value is “False.”

offset

integer

optional

This is the number of results that we have to return.

The default value is 100.

alias

string

optional

This indicates when to include alias locations in the results.

By default, alias locations are returned only in case there is no exact match for the search text.

Allowable values include "Never" and "Always."

Sample code

In the code below, we enter Seattle as our search text for the parameter q on line 1. You can try adding the optional parameter(s) to the URL on lines 3–4 to fine-tune your search.

Click the "Run" button to see the output.

Press + to interact
q = 'Seattle'
url =   'http://dataservice.accuweather.com/locations/v1/search/' \
        + '?q=' + q + '&apikey={{API_KEY}}'
response = requests.get(url)
printResponse(response)

The code above displays a list of all, or the specified number of, locations globally that match our given text, along with their detailed information, including the response parameters given in the table below. In case of failure, an appropriate error message is displayed.

Response parameters

Parameter

Type

Description

Key

string

This is the unique location key of the city.

Rank

integer

This is the rank designated on the basis of population, political importance, and geographic size.

LocalizedName

string

This is the name of the location in the requested language. Its default language is “en-us.”

Country

object

This contains information regarding the locations's country, including its code, and its localized and English names.

Timezone

object

This contains information regarding the location's designated timezone.

Geoposition

object

This contains information regarding the location's geographical position, including its coordinates.

Note: The list of response parameters above is not exhaustive. Please refer to the appendix for details of the response.