Ocean Getaways by Team Boneless Ice

Ayham Alnasser, Clement Chan, Kiran Vuksanaj, and Tiffany Cao (PM)

PROGRAM OVERVIEW:

This website is essentially a helping guide to travelers going to other cities or countries globally. There is a single search form, allowing the users to input a city and country, which will be stored in a session. If the given city and country doesn’t exist, is ambiguous, or is misspelled, the website will show an error message and refresh the page. Using the IP Stack API, we can obtain the user’s location and country, for which we can then find local currency using the MapQuest API. The same is done for the user’s desired city and country. This information is used to compute the currency exchange rate and make conversions, using the Currency Exchange API. The website will also show information regarding the weather of the city given using the Dark Sky API. Finally, using the Wikipedia (for images) and MapQuest APIs, users will be provided with images and a map of the city they gave, respectively. As an extra feature, there will also be a small section extracted from the Wikipedia API about the city given (taken from the Wikipedia page of that city).

ROLES

FRONT END

• Kiran (Bootstrap)
• Tiffany

BACK END (APIs)

• Clement: retreive and display weather information weather, map display with zooming (MapQuest, Dark Sky)
• Kiran: retrieve base city information (REST Countries, IP Stack), caching of city information and map display into database
• Ayham: retreive information on city and city images, IP address obtainment (Wikipedia, IP Stack)
• Tiffany: currency conversion and exchange rate database, weather information display with images (Currency Exchange, Dark Sky)

INSTRUCTIONS FOR INSTALLATION

Before beginning, ensure that you have access to git commands and python3 on your terminal. If you have only python3 and not python2 installed, all instances of pip3 and python3 may be replaces with pip and python.

In order to download the source code for the app, call

git clone https://github.com/TiffanyCao/p01.git

Navigate into this directory, and install the necessary python library requirements with

pip3 install -r requirements.txt

If you do not have access to the pip3 command, you can instead create a virtual environment with

python3 -m venv <virtual_environment_name>
. <virtual_environment_name>/bin/activate

and then resume installing normally.

Procure keys for the Mapquest developer API and the Dark Sky Weather API before proceeding. When you have successfully procured keys, replace the dummy text in keys.json with your request keys. See below for instructions on key installation!

The app can be launched when keys have successfully been procured with:

python3 app.py

OBTAINING KEYS

None of the below keys require payment information for the beginning of usage. The only necessary resource is an email address.

MapQuest Developer API - Geolocation

Documentation here

1. Register for an account on MapQuest Developer

• While you do have to fill out all fields, none matter other than your email address.

2. The landing page post-signup will contain an app titled 'My Application' already created; open the card for the app, and copy the consumer key
3. Open the keys.json file in your repository, and paste the key in place of YOUR_API_KEY_HERE in the 'mapquest' field

Dark Sky API - Weather Forecast

Documentation here

1. Register an account on Dark Sky API

• the only required fields are an email and password

2. Confirm your email address by clicking the link sent to the email address entered, and then log in with your new credentials
3. Copy the secret key displayed on the landing page post-login, and paste it into keys.json in place of YOUR_API_KEY_HERE the 'darksky' field

IP Stack API - Geolocation part 2

Documentation here

1. Register an account on their site
2. Open dashboard and yoink the API key you're given
3. Drop the API key into the 'keys.json' in place of the 'YOUR_API...' in the 'ipstack' field

OTHER APIs USED - NO KEYS REQUIRED

1. Wikipedia API: This API is used to obtain information on the city, as well as display images of the city in the information page. The Wikipedia API is very expansive and has many different query calls; here are the main calls we used in Ocean Getaways.

• For obtaining text information: action = query, list = search, srsearch = {city name}, prop = extracts, explaintext, exintro, titles = {title of Wikipedia page}
• For obtaining urls of images: action = query, titles = {image title}, prop = images, prop = imageinfo, iiprop = url
• Documentation here

2. Currency Exchange API: This API is used to obtain currency exchange rates between a given base country and 70 other currencies in the world.

• Documentation here

3. REST Countries API: This API is used to obtain the local currency of a given country. Used in conjunction with IP Stack to find the country the user's IP address resides in and the currency of that country.

• Documentation here