Getting a List of Locations

Learn how to get a list of top cities worldwide and countries within a given region.

We'll cover the following

The Locations API allows us to get detailed information about places around the globe. Among other information, it provides the unique key for each location as well. This key is important since we'll use it in the coming lessons to invoke other APIs to get various kinds of weather data.

In this lesson, we'll learn how to get a specified number of top cities around the globe with detailed information. Moreover, we'll also learn how to get a list of all countries from a given region, along with their basic information.

List the top cities in the world

The Top Cities List endpoint allows us to retrieve a list of the top cities in the world. The ranking of the cities is based on a number of factors including, but not limited to, the population of the city, its political importance, and its geographic size. This endpoint provides detailed information for each city, including its geographical position, timezone, and population. Using this endpoint, we can retrieve information for the top 50, 100, or 150 cities worldwide.

Let's make a GET request to the following URL to get a list of a certain number of top cities around the world:

Press + to interact
http://dataservice.accuweather.com/locations/v1/topcities/{group}

Request parameters

Parameter

Type

Category

Description

API_KEY

string

required

This is our API key.

This is a query parameter.

group

integer

required

This is the number of cities we have to retrieve.

The allowable values are 50, 100, and 150.

This is a path 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.

In the code below, we set the parameter group to 50 on line 8. You can try adding the optional parameters, language and details, to the queryParameters object on lines 19–21 for fine-tuning the results.

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 path parameter here
const group = 50;
// Define endpoint URL here
const url = new URL(`http://dataservice.accuweather.com/locations/v1/topcities/${group}`);
// Define header parameters here
const headerParameters = {
  contentType: 'application/json',
};
// Define query parameters here
const queryParameters = new URLSearchParams({
  apikey: API_KEY,
});
// Setting API call options
const options = {
  method: 'GET',
  headers: headerParameters,
};
// Function to make API call
async function getTopCities() {
  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
getTopCities();

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

  • Line 8: We define the path parameter group.

  • Line 11: We define the endpoint URL.

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

  • Lines 30–41: We define a custom function getTopCities() 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 getTopCities() function.

The code above displays the specified number of top cities around the globe and 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 city's country, including its code, and its localized and English names.

Timezone

object

This contains information regarding the city's designated timezone.

Geoposition

object

This contains information regarding the city'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.

List countries from a specific region

The Country List endpoint allows us to retrieve a list of all countries from a specific region. It also provides some basic information about each country, including its ISO country codeIt is a 2-letter or 3-letter internationally recognised code for a country., its localized name, and its English name.

We make a GET request to the following URL to get a list of all countries from a region of our choice:

Press + to interact
http://dataservice.accuweather.com/locations/v1/countries/{regionCode}

Request parameters

Parameter

Type

Category

Description

API_KEY

string

required

This is our API key. 

This is a query parameter.

regionCode

string

required

This specifies the region to get all the countries from.

Allowable values: ASI, MEA, EUR, AFR, OCN, NAM, CAC, SAM, ARC, ANT.

This is a path 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.

In the code below, we enter NAM, which is the region code for North America, for the parameter regionCode on line 8. You can try adding the optional parameter language to the queryParameters object on lines 19–21 to get the results in a language of your choice.

Click the "Run" button to see the output.

Note: Please refer to the appendix for all the regions and their corresponding codes.

Press + to interact
// Importing libraries here
import fetch from "node-fetch";
// Define API key here
const API_KEY = '{{API_KEY}}';
// Define path parameter here
const regionCode = 'NAM';
// Define endpoint URL here
const url = new URL(`https://dataservice.accuweather.com/locations/v1/countries/${regionCode}`);
// Define header parameters here
const headerParameters = {
  contentType: 'application/json',
};
// Define query parameters here
const queryParameters = new URLSearchParams({
  apikey: API_KEY,
});
// Setting API call options
const options = {
  method: 'GET',
  headers: headerParameters,
};
// Function to make API call
async function getCountries() {
  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
getCountries();

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

  • Line 8: We define the path parameter regionCode.

  • Line 11: We define the endpoint URL.

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

  • Lines 30–41: We define a custom function getCountries() 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 getCountries() function.

The code above displays a list of all countries from the specified region. For each country, it provides the information given in the table below. In case of failure, an appropriate error message is displayed.

Response fields

Parameter

Type

Description

ID

string

This is the unique ISO country code.

LocalizedName

string

This is the country name in the local language.

Its default language is en-us.

EnglishName

string

This is the country name in the English language.