Locality

Submission Track

Our submission falls under Track 3: Businesses.

Inspiration

The COVID-19 outbreak is hitting small, local businesses hard. From remote work to forced shutdowns, these businesses of less than 500 workers are fighting to survive as this virus shocks our U.S. economy. We also realize that during these trying times, there is a plethora of misleading information. As it is important to have reliable sources to turn to, especially when people’s lives are on the line, we wanted to create something scalable, yet convenient, to tackle these big issues. Our project aims to be convenient for both local businesses and ordinary users.

As explained by Business Insider and other sources, there are many ways for communities to support local businesses, by taking advantage of online purchases, delivery options, and virtual gift cards. And now more than ever, local businesses stand to benefit immensely from business to business support and collaboration. Our product leverages these forms of support and allows businesses to highlight which of these options they offer and what requests they have for their local community.

What it does

Our webAPI is a one-stop shop for users to search for businesses and view their specific details, as well as for businesses to sign themselves up for display. Specifically, there are five pages. First, there’s the Search Page, which allows users to query by location (city and ZIP code) and category of business (listed in “How we built it”). Second, there’s the Results Page, which presents a summary of each listing as queried; it also allows users to perform a new search or click on a listing to learn more about the business. Third, there’s the Listings Page, which shows the full set of information provided by the business, including product descriptions, gift card availability, links to their social media and websites, contact information, and specific ways to support them; an important feature is the Call-to-action portion, which allows users to share their support for the business on Twitter, or personally email the business owner for further contact. Fourth, there’s the Sign Up Page, which is a Google Form with the relevant input fields that a business will enter (i.e. contact info, location, existing online infrastructure, any ideal requests, etc.). Fifth, there’s the Admin Page, which is not currently functional, but will be described in our “What’s next” section.

How we built it

First, we made a project on AWS Elastic Beanstalk. Next, we started with the AWS sample code (a baseline Python WSGI server) and iteratively added the following features:

Added free-use Bootstrap project
Found free-use sourced images from Pexels
Divided into templates and static resources, where templates had variable portions that could be dynamically rendered. Added Jinja2 to render templates, and updated templates for basic variables (i.e., variable paths, data, links, etc.)
Added wsgi_static_middleware to serve the static resources (from the server)
Created a conditional block to determine how GET/POST requests would be handled for each path (e.g., the default GET request for an invalid path links to the main search page...)
Setup a service account on Google Cloud for the server to use Sheets API through the interface “pygsheets” without verification per-user
Linked a spreadsheet to the Google Form and stored its Sheet ID (to access it through the API)
Protected credentials and private low-level implementation details (like ID’s) through abstraction and the .gitignore file
Developed a module to retrieve records (dictionaries) for each business submission on the Google Form linked spreadsheet (using “pygsheets”)
Looked into ways to parse site-specific form submissions, and added cgi to parse the POST request into queries (from the front-end search form)
Made query system by doing the following: (A.) With an input from the parsed request: (B.) Searches the rows of the spreadsheet for City matches (C.) Then uses a hard-coded dictionary from general site business types (i.e., ‘food“,”store”,”fitness”,”etc.”) to specific business types on the Google Form (i.e., “cafe”,”bookstore”,”gym”) to filter matches (from the search form) (D.) Finally, returns entries with matching ZIP codes first and all other ZIP codes last (no distinguishing between ZIP code distance for the proof of concept demo). In other words, the results with appear first have matching ZIP codes (as a guarantee). (E.) Returns a list of the queried rows to the front-end to loop over and create summary blocks for each result business (storing all submitted information, as well as the ROW id in the spreadsheet)
Making listing page: (A.) Implemented a scheme where each page has a url “business/NUM” where NUM is the corresponding row in the database (for a reliable scheme that would require minimal data passing between server and client to ID a business) (B.) Ensured each page has a Twitter query and Email query link for easy sharing on Twitter and easy contacting the business via email (C.) Designed a new dynamic template to showcase all of the important details from the business and a logical UI (using the information passed from the server)
To test our API, we did the following: (A.) Tested locally for development (used “localhost:8000” to access) (B.) Zipped and deployed on AWS to test scalability (in about 12 waves) (C.) Generated seed data (fake form responses) as a stress test (using a flow: Python => CSV => Google Sheet)

Challenges we ran into

Our first challenge was a bug where credentials had to be accessed repeatedly to authorize Google Sheets API. Then, we had the challenge of transition from Local Development to AWS server, specifically using a different representation of strings (as unicode vs. bytestrings) and adding a “requirements.txt” file (which had already been installed locally) to import packages to the AWS server. We also had to use logging to debug both locally (localhost) and on AWS (looking at AWS logs). Next, we faced the challenge of accounting for all the edge cases in the input query. Finally, we had to deal with processing too much data in a small request, ensuring that accessing a single listing does not require a full-database query.

Accomplishments that we’re proud of

We are proud of successfully connecting the individual components of the project to form a robust workflow involving links between businesses (Google Forms), database (Google Sheets API), backend (Python WSGI server), and frontend (HTML site and user queries). Additionally, we are proud of finding and using various resources, including Bootstrap and pygsheets, to build our site, and transforming AWS sample code into a functional web application tailored to our project goals. Finally, we are proud that we were able to build a product that will help communities during this crisis, with benefits at the local level yet applicability to businesses across the nation.

What we learned

On the technical side, we learned how to use AWS to host a webserver, while utilizing various resources for streamlining the flow of data from business to site to user. We also learned that when generalizing HTML templates to dynamic input data, it is possible to create a database results/listings unit that can flexibly present database content in subpages without adding new HTML. Finally, we learned the importance of ensuring that locally installed packages are deployed along with the web application.

We also learned how to identify real world problems and turn them into scalable solutions using our technical skills. Additionally, this project made us realize that local businesses have a fair chance of being supported because they have corresponding local communities that can access them.

What's next for Locality

Here are some technical updates we hope to implement:

Having admin approval (A.) Adding a feature that allows admin (or an automatic filtering process) to verify submissions form businesses before submitting to the database, to prevent misinformation.
Addressing more business needs (A.) Providing an interface for businesses to update their profiles as their situation changes over time. (B.) Including a real-time map to dynamically view the businesses in a specified area; this allows users to visualize and track the local businesses accessible to them.
More search/query functionalities (A.) Providing a more thorough search process that filters by distance (ie specifying an X mile search radius and then ordering results by distance). There can also be an option to filter by keywords. (B.) Streamlining/refining the way data is queried: querying more in the Sheet itself (for the back-end API call, to reduce how much data is sent to the server from Sheets) and having the front-end render data in smaller segments (i.e., results sub-pages so not all results are shown on the same page). These would reduce the time it takes to load data (on the server-side and client-side). (C.) Addressing the timeout of Google Sheets API if too many requests are made at once (nothing breaks, but it freezes). We didn’t feel this was a major issue for a demo, but this can be fixed by transferring the database to something that scales with the number of requests (eg, an AWS database). We chose to keep Google Sheets API for its simplicity and ability to link with the Google Form, although there are other ways to configure the form to avoid reliance on Google Sheets. These new platforms and technologies will be explored in the future.
More user options (A.) Adding a feature where users register their address and are contacted when new businesses create accounts on the service. (B.) Adding options for sharing listings via email and more social networks like Facebook, Instagram, etc.

These next steps all help our goal of maximizing Locality’s impact. As the name suggests, Locality aims to serve as a central hub that aids communities in allocating locally sourced products and supplying businesses with resources during this pandemic. Our primary next step is to make this platform available across the nation, thereby allowing everyone to tackle some challenges from COVID-19 by supporting local businesses and fostering meaningful collaboration. In doing so, Locality allows us to solve a global problem with the power of our own, local communities.