Understanding Address Coordinates in gaiia

Overview

Address coordinates — the latitude and longitude values tied to a customer's service location — are used throughout checkout in gaiia to power product availability, appointment scheduling, and work order creation. This article covers why coordinates matter at each stage of the checkout and order process, and how gaiia retrieves them.

Understand why address coordinates matter

Coordinates serve three distinct purposes in gaiia's checkout and order flow.

Product availability filtering

When a customer enters their service address, gaiia uses the associated coordinates to check which products are available at that location. This determines which plans are shown to the customer during checkout. Without a valid coordinate, the product catalog cannot accurately evaluate service area eligibility.

Appointment scheduling

Coordinates are used when retrieving available appointment time slots and when determining technician assignment. gaiia passes the location's coordinates to the workforce service to retrieve available times and identify the appropriate technician — this query determines which appointments are surfaced on the scheduling calendars in checkout and the client portal. Coordinates also determine the service address timezone, which ensures appointment times are displayed correctly to the customer during checkout.

Work order creation

This is the most critical use of coordinates. When an order is processed, coordinates from the customer's physical address are sent to the workforce service to support technician auto-assignment and travel time calculation. If coordinates are missing at this point, work order creation fails and the order cannot be fulfilled.

Understand how gaiia retrieves address coordinates

By default, coordinates are retrieved automatically when a customer selects their address during checkout. When the customer picks a suggestion from the address lookup, gaiia fetches the associated coordinates from the address suggestion API (Postcoder, MapBox, or Smarty) and carries them through the rest of the order flow — storing them with the order at submission and saving them to the customer's account for use during processing.

Because automatically retrieved coordinates can sometimes be imprecise, gaiia also supports a manual confirmation step. When Address geocoding is enabled, a MapBox widget appears in checkout after the customer enters their address. The customer places a pin on their exact location to confirm it, and the coordinates from that confirmation overwrite those retrieved by the API.

When Address geocoding is enabled (recommended)

1. The customer enters their service address and selects it from the address suggestions shown.
2. A map appears with a pin pre-placed at the location returned by the API.
3. The customer confirms the pin position or drags it to their exact location.
4. The confirmed coordinates are submitted with the order and saved to their account.

If MapBox cannot resolve coordinates for an address, the map will default to a central location and the customer will need to zoom in and place the pin manually.

When Address geocoding is disabled

1. The customer enters their service address and selects it from the address suggestions shown.
2. gaiia fetches coordinates for that address automatically from the API.
3. The coordinates are submitted with the order and saved to the customer's account.

The customer is not asked to confirm anything — coordinates are captured silently based on the selected address suggestion.