The task at hand

Our client Calor Gas approached us with a request to build a 'Find a Stockist' facility using a custom Magento module that allows users to find fulfilment agents (Calor's terminology for stockists) within their proximity. Calor Gas requested that the feature list the 10 nearest stockists. The ability to easily manage the list of stockists (along with the data associated to each stockist - such as the services they provide) was also required, as was the ability to prioritise certain stockists over others.

How we did it...

To calculate the distance between two points on the surface of a sphere, we decided to use the Haversine formula:

The haversine formula. Image:

The haversine formula. Image:[/caption]We also decided to utilise the Google Maps API, allowing us to search by coordinates. (Calor provided geographic coordinates for each stockist – this gave more accuracy than searching by address). A custom module was built that handles both the frontend and the backend implementation.

Backend implementation:

An interface was built (based on Magento's admin grid system) that enabled the client to easily add/edit/delete all details for each stockist. For longevity, as the list of stockists grows with time, we extended the module with an import facility to take CSV files containing stockist information. This allowed the client to avoid lengthy manual data entry, made it easier to maintain, and provided a smoother merge of data from the off-line to live site.Next we built a report interface; the client wanted to see how popular this feature was and how often certain functionalities within it were used. The report shows how many times a stockist's name came up as a result of a location search, where it ranked within the results, how many times it was selected from the list of results and how many times the 'Additional information' was accessed.

Stockist report in Magento.

Frontend implementation:

The Google Maps API was integrated to enable the search facility, and to display the stockists clearly on the map. Custom Google Map markers were used to further promote the brand: 'Calor Centre Stockists' (a more prominent marker) and regular stockists (a smaller but still customised marker).

Customised Google Map markers.

Customised Google Map markers. [/caption]Google Maps API also allowed us to provide driving directions from the user's location to the selected stockist (making directions available for print). Users could search for stockists that provided specific services, which then filtered the Google Map accordingly. The scope of the search could also be modified by selecting one of the predetermined mile radiuses from a dropdown (eg. within a 10 mile radius of location). The tool has since been one of the most widely used features on the Calor Gas website. Please visit the site to see the feature in action: