My Neighborhood Map

Application link: https://rahulbethi.com/neighborhood_map

This is my Neighborhood map (web app), built by myself Rahul Bethi.

It shows some of the places I love in Bay area, California.

It uses Google Maps API to show a customized map, with my favorite places as markers on the map. Click the markers to get more info of the places. Google Street view near the place. Foursquare API is used to get more info about Cafés. All these places can be searched and filtered by category.

This app uses a PostgreSQL database and Python server to get the places in JSON format. It then processes this data and shows them as markers on the map.

Built using

• HTML, Javascript, Knockout JS v3.4.2 (organizational framework), Google Maps API v3.31, Foursquare API v2 20170801.
• Python v3.6.4 (web server), PostgreSQL v10.3 (database).

Instructions to run

1. Install database software - PostgreSQL v10.3.
2. Install Python v3.6.4, and then pip install:
   • flask (microframework for Python)
   • sqlalchemy (Python SQL toolkit)
3. Setup Database:
   • Setup a database.
     • I used pgAdmin 4 v2.1 which is installed along with PostgreSQL database software for Windows.
   • Make a new json file named secrets.json in database_server folder.
     • Fill out the JSON file with database name, username and password to access the database.

       {
           "postgresql":
           {
               "user": "USERNAME",
               "password": "PASSWORD",
               "database": "DATABASE_NAME"
           }
       }

   • Run database_setup.py using Python to setup the database with the Listing table.
   • Populate the database with values by running init_values.py using Python.
4. Run app.py using Python, the app will be up and running on localhost:5000 address. Press Ctrl+C a couple of times to stop the server.
   • You can check the database server (python app) JSON output at http://localhost:5000/listings/json.
   • Note: If you change the server-address(here) and JSON data end-point(here) in the web server (app.py), you need to update it here (viewModel.js) as well.
5. Get a Google Maps API key and Foursquare API Client ID and Client Secret.
   • For Google - Create a project and add Google Maps Javascript API and Google Street View Image API to your project.
6. Make a new json file named secrets.json in the root folder.
   • Fill out the JSON file with the Google Maps API key and Foursquare API Client details.

     {
         "google": {
             "key": "GOOGLE_MAPS_API_KEY"
         },
         "foursquare": {
             "client_id": "FOURSQUARE_API_CLIENT_ID",
             "client_secret": "FOURSQUARE_API_CLIENT_SECRET"
         }
     }

7. Open index.html.

Design

1. PostgreSQL database is setup and stored with the data about my favourite places.

   • Database can be accessed by Python (using SQLALchemy toolkit) using the database name, username and password located in the secrets.json file inside database_server folder.
   • Python file database_setup.py creates the 'Listing' table in the database.
     • Each place (column of table 'Listing') contains: name, category, location (latitude, longitide), and description.
   • init_values.py python file adds some of my favorite places (in Bay area, California) to the 'Listings' table in the database.

2. Python web server (app.py) runs at localhost:5000.

   • It extracts the places from the database and sends back in JSON format at http://localhost:5000/listings/json.

3. The Web-app (index.html) is our main app.

   • It calls two javascript files init.js and viewModel.js.

4. The init.js Javascript file inititates the map and then calls the Knockout JS to bind with rest of the code, as everything is dependent on the Google Map.

   • It first extracts the API Keys from secrets.json JSON file in the root folder.
   • It then loads the Google Maps API script using the Google Maps API key in an asynchronous way.
   • Knockout JS is setup after the Google Maps API is loaded.

5. The viewModel.js Javascript file is the View-Model of the Knockout JS organizational framework with all the observational variables and bindings. It also has other functions and variables (Google Maps API, Foursquare API and search-filter features).

   • It requests the places data from the database sever we setup earlier.
   • With the obtained JSON data, it creates 'places' objects with Google Maps API Markers.
   • Categories of all the places are noted to filter out places with categories.
   • It also has all other remaining variables and functions related to the functionality of the web-app.

6. Web-app consists a map with Markers of all the places. Each Marker is located at the latitude and longitude of it's place on the map. Web-app also has a 'Show Listings' button on the top-left corner.

7. Markers: Clicking on each Marker on the map will open a small window with name, location (latitude, longitude) and description of that marker's place.

   • Google Street View -- Web app then requests the Google Street View Image API service to get the nearest 360 image and displays it in that window, when received.

   • Foursquare -- For cafés, there will be a button 'More info' in that window to search for Foursquare data about the café. Clicking that button will request Foursquare API Search for Venues service to search for the café with the name and location (latitude, longitude) of the café along with Foursquare category ID for cafe - 4bf58dd8d48988d16d941735. Received response (JSON) will have some details about the café along with its venue ID.

     • Note: Not all places are available on Foursquare, a sorry message is displayed when a café is not found.

   • Using this venue ID, a different request is made to Foursquare API Venues service for more details. Received response (JSON) will have all the details about the café. website, rating, working hours and Foursquare link of the café are taken from the response and displayed.

     • Note: Not all places will have all the details.

   • Each Marker has three icons.

     1. Default icon - normal
     2. Highlighted icon - when mouse hovers over the marker.
     3. Selected icon - when the marked is clicked and info window is opened.

   • Drop-animation is played when a marker is shown after hiding them.

8. Listings side-bar (place's link): Clicking on the 'Show Listings' button will open a side-bar with all the place names as links. Here, the word Listing is used for a place's link.

   • Clicking a Listing is same as clicking that place's Marker, but also closes the side-bar.
   • The side-bar also has search feature to search for places and show the short-listed Listings. It has three elements.
     1. An input field to type the place name or category name.
     2. A drop-down menu to choose category - to filter out places with that category.
        • Options of this menu is taken from the categories of all places.
     3. A 'Clear' button to clear the input field and reset drop-down menu to 'All' places.
   • Listings can be scrolled up-down, if they don't fit in the page.

9. Search (filter): Search is done as you type, for each character or option selected.

   • First, category drop-down menu (filter) is checked. 'All' option represents all places. Selecting any other category option will filter out places which are doesn't belong to that category.
   • Next if the input field is not empty, then the input text is matched with the name of the places from category filter. Matched places are showed as Listings. Even Markers of unmatched places are removed from the map.
   • Input is also matched with category names of places if the category filter is set to 'All'.
     • Example: Typing in cafe will also match with Starbucks as it is of same category (only when category filter is set to 'All').
   • Union of above two searches (place name search and category name search when category filter is set to 'All') is finally displayed as Listings.
   • Special characters, spaces are ignored for convinience. All letters are converted to small-caps.
     • Example: Typing in suesgall or sues gall or sue'sGall etc. will give same result Sue's Gallery Cafe.
   • Even if the input is a middle word, it is matched.
     • Example: Typing in hwy or h w y etc. will give same result Cabrillo Hwy and Panaromic Hwy.

10. Clicking anywhere on the map will close the info window of a place and also the side-bar (if it is open).

Error detection

1. If Google Maps API is not loaded - checks after 5 seconds of Google maps callback function init_map().
2. If API Keys are not found in secrets.json file in root folder.
3. If both secrets.json files are not found or couldn't be accessed.
4. If database server couldn't be reached.
5. If no places are present in the response from the database server. Database might be empty.
6. Google Street View Image API service error inside info window of marker.
7. Foursquare API Search for Venues service data fetching error.
8. Foursquare API Venues service data fetching error.
9. If no place was found while searching for Foursquare data.
10. If no places (lisitngs) were found in the search (filter).

Other details

• Styling file style.css is in css folder.
• Images for Marker icons are in images/marker_icons/flag folder.
• Screenshots are in screenshots folder.
• Address to my hosted app: https://rahulbethi.com/neighborhood_map

My Webpage

https://rahulbethi.com

My LinkedIn profile

https://www.linkedin.com/in/rahulbethi