Text Search

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

We'll cover the following

In this lesson, we'll 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.

Press + to interact
http://dataservice.accuweather.com/locations/v1/search

Request parameters

Parameter

Type

Category

Description

API_KEY

string

required

This is our API key.

This is a query parameter.

q

string

required

This is the search text.

This is a query parameter.

language

string

optional

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

Its default value is en-us.

This is a query parameter.

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.

This is a query parameter.

offset

integer

optional

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

The default value is 100.

This is a query parameter.

alias

string

optional

This indicates when to include alias locations in the results.

By default, alias locations are returned only in case of no exact match with the search text.

Allowable values include Never and Always.

This is a query parameter.

In the code below, we enter Seattle as our search text for the parameter q on line 16. You can try adding the optional parameter(s) to the queryParameters object on lines 18–21 to fine-tune your search.

Click the "Run" button to see the output.

Press + to interact
// Importing libraries here
import fetch from "node-fetch";
// Define API key here
const API_KEY = '{{API_KEY}}';
// Define endpoint URL here
const url = new URL(`http://dataservice.accuweather.com/locations/v1/search`);
// Define header parameters here
const headerParameters = {
  contentType: 'application/json',
};
// Define query parameters here
const q = 'Seattle';
const queryParameters = new URLSearchParams({
  apikey: API_KEY,
  q
});
// Setting API call options
const options = {
  method: 'GET',
  headers: headerParameters,
};
// Function to make API call
async function getLocations() {
  try {
    url.search = queryParameters;
    const response = await fetch(url, options);
    // Custom function for printing the API response
    printResponse(response);
  } catch (error) {
    // Custom function for printing the error message
    printError(error);
  }
}
 
// Calling function to make API call
getLocations();

Let's take a quick look at the code given in the widget above:

  • Line 8: We define the endpoint URL.

  • Lines 16–21: We define the query parameters.

  • Lines 30–41: We define a custom function getLocations() to make an API call using fetch and handle any exception if it occurs. The custom functions printResponse() and printError() are used to print the API response and errors, respectively.

  • Line 44: We invoke the getLocations() function.

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

Response fields

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 location'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 fields above is not exhaustive. Please refer to the appendix for further details of the response.