Why?

"Store locators" are a common use-case for most retailers or organisations with physical premises. We have built them for a few of our clients and it's time to make a generic example that anyone can understand and learn from!

What?

A tutorial showing how to build a "find my nearest X" (AKA "store locator") using freely available location data, PostgreSQL, ETS and Elixir/Phoenix.

Note: The end result should be a reasonably attractive browser application that allows the person to input a UK postcode and will display both their postcode location and the location of the n nearest X on a map with the list below the map showing the distance to the X. Clicking on the link in the list should open the default map application on the device or if it's a desktop/laptop should open Google Maps in full-screen using a target="_blank".

Who?

People who want to learn about Geolocation, Google Maps, Distance calculation and rapid lookups in medium-sized datasets. Anyone who wants to learn how to build a real-world "store finder" in Elixir/Phoenix.

Why is @RobStallion our best person to write this example/tutorial? Simple: he has both the professional experience having worked for DPD couriers so he is personally aware of the "Travelling Salesman" problem ... Incidentally, DPD has a decent "Store Locator": https://www.dpd.co.uk/apps/shopfinder/index.jsp Which has much of the functionality this example will have. I leave it to you to determine if the UX is the best it can be. (or if the UI is a bit "cluttered" ... 🤔)

How?

@RobStallion please estimate how long it will take you to convert the knowledge you gained while building the feature for our client: https://github.com/club-soda/club-soda-guide/pull/291 into a stand-alone example app that allows people to input their postcode and find the nearest X (where X is your choice of "vegan restaurant", "train station", "free outdoor gym" ... - or whatever data is publicly available, interesting to you and easy to parse... 😉)

Todo

• Start by documenting the raison d’être of the repo (expanding on what I have written above) our Objective with this example/tutorial is 4-fold:
  • 1. Clearly explain to everyone in the CS team how the "Venue Locator" functionality works. (our current team might all understand the code because everyone read/reviewed the PR, but both future team members and the client's internal/external maintainers will not. so our objective is to have comprehensive documentation that answers all their questions proactively)
  • 2. Create a generalised learning resource that anyone in the community can use to understand the concepts and apply them practically:
    • What are Longitude and Latitude? (give a micro history lesson to contextualise)
    • What is Geolocation?
    • What is Geocoding? (geo-encoding)
    • What is Reverse Geocoding?
      • The Example app should Ask people for access to their location in the browser. https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API
  • 3. Demonstrate the benefits Phoenix/Elixir and it's "free" in-memory Database ETS which allows for the fastest possible lookups; even faster than XYZ programming language Redis!
    • Our objective is to make the "find nearest X" as fast as it can be to demonstrate that Phoenix/Elixir is the logical choice that all websites should be built with. Once the Heroku app boots, the response time for a lookup should be sub 200ms. 🏎
      • Load the Google Maps JS library in the footer of the home page so that pins will appear fast.
      • Show one result for the "nearest X" as text. then display the map, then the list of nearest X's ... i.e. create a "content hierarchy" based on relevance to the user.
  • 4. Practice Technical Writing Skills. Writing is the single best way to practice your thinking skills. Communicating your knowledge/understanding of a topic with others is the difference between a beginner and a senior engineer. It's the reason all universities require students to teach before they can "level up". The more teaching you do the better you will understand the topic and forcing yourself to explain the material to a complete beginner means you have to understand it at a much deeper level.

Note: once the UK postcode "find nearest X" example is working, if you want to take this to it's "logical conclusion" and go global, open an issue to expand the tutorial to allow people to type in any address and use Google's/GeoNames geocoding API to find the Lat/Long and then lookup the nearest Airport (this gloabal data is freely available: https://openflights.org/data.html ...) the reason we aren't doing the global version first is that this example's first objective is to serve as comprehensive documentation for the CS functionality.

• You, the creator of this example/tutorial, are free to use your creativity/imagination for coming up with the UX/UI, but you should include examples of the best implementations on existing websites. i.e. go looking for real world examples of best and worst Store Locators for UK-based websites/services and list them in the "Appendix" of the example, similar to how you wrote the "YouTube" example in: https://github.com/dwyl/cid/pull/12
• If you get "stuck" ask questions!