# Note: This cell is for worldfinder development purposes only.
# If the current working directory is inside the docs folder, 
# this code will change it back to the project's root directory.
import os

if (os.getcwd().endswith('docs')):
    os.chdir("../")

Worldfinder Tutorial

Welcome to the Worldfinder package documentation! This package offers a suite of functions designed to give you information about any city or country that you are interested in. Here, we illustrate the usage of these functions with real-life examples, featuring James, a world explorer and developer passionate about geography.

James’s Journey

Ever since James was a child, he has been fascinated by cities and countries around the world. He’s even memorized the names of most major cities and countries. James loves this stuff and wants to try turning his passion into a game. The game would challenge players by asking questions about country capitals, country statistics, pairing cities with countries, and even trivia like how many countries share the same city names.

His idea is to have players input their answers in a text box, which will then be compared with the correct answer. To bring his idea to life, he needs a reliable source of country and city data—without incurring any costs from API calls.

This is where our library shines! It provides a robust dataset with 4 easy-to-use functions, which we’ll dive into below.

Let’s get started!

To use worldfinder in a project you should first do the following to import

import worldfinder

You can verify your worldfinder version by doing the following:

print(worldfinder.__version__)

0.0.1

James wants to start off his game with an easy question for his players, the capital! So he needs the answer for every country capital there is to compare his user’s answers with.

So, let’s get started with our first function:

get_capital

First, we’ll want to go into our library and get the function like below:

from worldfinder.get_capital import get_capital

Nice! Now that that’s loaded, all we have to do is pass the country name as a string to the function.

get_capital("Switzerland")

'Bern'

Nice! James now has a reliable way of getting the appropriate capital of any country he chooses to ask his players.

get_country_statistic

Say that James wants to have trivia questions in his game about certain information on a country such as how many people live there. Well with the worldfinder package, James can do that easily with our get_country_statistic function.

First let’s import the function below:

from worldfinder.get_country_statistic import get_country_statistic

Once the function is loaded, James can call it by passing in 2 strings: the first for the name of the country and the second for the statistic that he wants to look up. As of now, there are 5 acceptable options for the statistic string:

  • population: The number of people living in the country

  • gdp: The country’s gross domestic product

  • birth rate: Number of births per 1,000 population per year

  • cpi: Consumer Price Index, a measure of inflation and purchasing power

  • Unemployment Rate: Percentage of the labor force that is unemployed

Let’s try finding out what the population of Canada is:

get_country_statistic("canada", "population")

'36,991,981'

Looks good! James can now really quiz his players about the different aspects of the countries around the world!

check_city

James also wants to include another type of question in his game, where players guess whether a city is located in a specific country. To determine the correct answer, the check_city function from the worldfinder package can be very helpful.

To begin, we need to load the function as shown below:

from worldfinder.check_city import check_city

With the function now loaded, we simply need to pass the city name followed by the country name as a string into the function. The function will return a boolean indicating if that city is in the given country. Let’s test it out by checking if Manila is in the Philippines:

check_city("Manila", "Philippines")

True

Perfect, now James has a method to find the correct answer and use it to validate the responses his players provide.

get_countries

Did you know? London appeared not only in Britain but also in the United States and Canada. In fact, different countries may have the same city name. With the worldfinder package, James can test the knowledge of his players on how many countries share the same city names by using our get_countries function.

First let’s import the function below:

from worldfinder.get_countries import get_countries

Now we have get_countries successfully loaded and is there for James to use! James can input the city name as a string to the function and it will return a list of countries that all share the same city name.

get_countries("London")

['Canada', 'United Kingdom', 'United States']

Finally! James can now use all the different functions in the worldfinder package to get the answers to his trivias and start building his game!

Final Remarks

We hope these examples are informative on the usage of the different functions in our package. If anything remains unclear, we suggest reviewing the function documentation or creating an issue in our repository and we will get back to you.