Why? What? Who? How?

[nelsonic]

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: club-soda/club-soda-guide#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: adds section about youtube to readme #9 cid#12
• If you get "stuck" ask questions!

[RobStallion]

@nelsonic I think a rough estimation will be between 3 days for this. I'll write up more info on this break down in the near future and separate out the larger tasks if needed. Just wanted to get an initial estimation in

[nelsonic]

@RobStallion 3 days sounds like a good (optimistic?) estimate. ⏳
Please start as soon as you have availability (while the knowledge and pain is still fresh). 💡
Please use the opportunity to do some wireframes of the UI/UX, 📱
which will relate to: dwyl/learn-wireframing#1 so pick @Cleop's brains! 👍
Thanks! ✨

[RobStallion]

@nelsonic do you know any good tools for getting a json of address info for a random group of things, e.g. vegan restaurants, outdoor gyms?

I don't need it for the example as I can just use any random addresses but I thought that it might be a nice touch, and from your comment so did you...

(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... 😉)

I haven't yet done much googling around for a tool yet. I thought I would ask beforehand while I worked on other parts of the example.

[nelsonic]

@RobStallion yes, but it depends on what data you're going with.

[RobStallion]

@nelsonic Outdoor gyms?

I'm going to start with a list of random postcodes for now but it would be nice if they were all related in someway or another.

[nelsonic]

@RobStallion agreed. (what did Google say when you asked for a "list of UK outdoor gyms"...?) 🤔

[RobStallion]

https://data.gov.uk/dataset/bbd56d2d-0899-4be2-bb24-f02ff50c2592/outdoor-sports-facilities/datafile/a6cb4fcc-6d13-4f28-a62e-40fc230c1396/preview

[nelsonic]

@RobStallion The data you have found and used is only for Leeds Council. That's a good start. 👍

I reached out to Georgie & Matt Delaney co-founders of The Great Outdoor Gym Company (TGO)

You know, the company that makes the outdoor Gym Equipment you see all over London (and the UK!) 😉

to see if they can share their list of Outdoor Gym locations. (I CC'd you in the email so you are aware)
But you should move forward with the Leeds data in case they don't get back to us fast enough.

[nelsonic]

An alternative source of data might be https://calisthenics-parks.com/maps