Making Addresses Work

There are many reasons to visit a client. Whether it is for therapy, for sales or for delivery, the journey cannot start without an address.

Thus software needs to deal with the concept of physical real-world locations. In this blog we’ll show some code that can make addresses useful in our apps.

What are common use cases?

1. Entering, validating and normalizing addresses.
2. Searching for clients by geographic query - like which clients live in this city or region
3. Planning a trip with one or multiple client visits
4. Logging completed visits

Before we start, we have to look a little closer at what an address is.

(Civic) Address

First we have the familiar civic address. That is the street number, city and country.

Folks from US add also the state, since there are many Springfields.

What’s more, if you live in an apartment in a multistory building, to be precise you might also need the floor and apartment number.

On the other hand smaller villages might not even have street names. In Slovakia you might have only a house number.

Because we might want to send something by mail to a given address, we often add a zip-code. Of course the code differs by country and there usually is no 1:1 mapping between city and zip. Sometimes smaller villages share a code while bigger cities have multiple codes.

Truly large cities might need further identifiers like the borough (New York’s Manhattan, Bronx, etc.).

While there is a level of standardization, the details are messy and differ between countries. Our few examples only scratched the surface.

If you like more hairy details, OSM has a great write up about the many levels of address parts

If we only care about the actual physical location of an object like a building, we use the geographic address: the longitude and latitude. These two numbers tell you an exact spot on earth. Why do we need it? First of all, your phone has a gps module and it tells you your location in lat&lon. Next, when you wish to show a place on earth on a map, you need to use lat&lon. Or you might wish to lookup objects that are 50 miles from a particular location. Finally, there are many places that don’t have a civic address, fields, forests, basically any places far from human habitats. And even for buildings a civic address might not be precise enough.

Depending on the need, we might use one or the other address, but what if we only have the other one?

Converting addresses

Geocoding is the operation that translates a civic address into latitude&longitude (and sometimes elevation). There are many online services that offer geocoding.

• Google
• Azure
• OSM and derived services.

OSM allows you to take (same) of the address data and build your own service too.

Naturally we might also wish to reverse the process. That means given a latitude and longitude, what is the civic address. Intuitively it is called reverse-geocoding. Service providers usually offer both.

Civic address validation

When users enter a civic address there is a lot of room for error. Usually we ask users to enter the street, city and zip separately just to catch the most obvious problems. We can go further and make the city or even the address not a text field but an options-list, which eliminates even more typos. In order to implement this functionality you can use the overpass services to get a list cities, towns and villages within a country It is also possible to retrieve a list of cities

In many countries it is also possible to get government geo data. In our experience OSM usually already incorporates these data sources. Finally postal services publish information for zip code to city and/or street mapping.

Geographic address (latitude & longitude)

Most of the time it is useful to keep the lat&lot coordinates along the civic address.

1. Automatic conversion: whenever we get a civic address we will geocode. This can be implemented in a way that is invisible to the user, for example on the backend. Why should you implement automatic mode? It will ensure each address has a latitude and longitude, whether it came from user input or it was imported from a file or collected through api.

2. Manual conversion: the geocoding process is available as a button for the user. This can in addition to the automatic mode. Why should you add manual conversion? Your users might want to verify the result of the geocoding - that the location on the map actually corresponds to the address. And they might adjust the address to get a more precise location. For example when the place is a football stadium, clients might choose to precisely mark the entrance or alternatively the preferred parking area.

3. Address from my position: Instead of asking the user to enter their current address, we can instead use their latitude and longitude (from the phone’s gps) location and then reverse-geocode the civic address. Why do this? Clients can enter the address for delivery or service location with one click. This means fewer errors and a higher completion rate by clients.

4. Address from map: Similar to the previous point, we can let the user pick their location on a map. We can of course combine this feature with any of the previous ones. First we get the geo location from the civic address or gps and then let the user verify and fine tune the geo location on the map.

Let’s look at some possible client journeys when entering an address

1. User enters the civic address manually
2. App can geo-code the address automatically (first level of validation)
3. App can display the converted address on a map
4. User can fine tune the displayed location on the map (by dragging the pin for example)
5. The app can offer reverse-geocoding the civic address when the pin is moved. (Whether to do this automatically depends on your scenario, we recommend to do this only on manual action, or only after a significant movement.)

Alternative B

1. User asks the app to lookup their location via gps.
2. The app reverse-geocodes the geo-location to a civic address
3. The journey continues with a A3

Alternative C

1. User places (or drags) a pin on map to choose their location. Of course it makes sense to display the map near the user’s actual location.
2. The app can let the user search the map (by city names for example)
3. App can continue with step B2

This is our everything and the kitchen sink implementation. Granted, this is targeting skilled users, who do need the features. But this could be too much for the average user. It is best to start simple - with what the users need.

Filtering records by address or location

Retrieving a list of customers from a city is a straightforward database operation. Assuming the city name is normalized (for case and accent) and stored in a searchable way - eg as a separate db column. Often we are more interested in places being physically close, for example customers within 20km from my location. In this case we need query by latitude and longitude.

Converting meters to lat and lon is not a particularly complex operation. Thus we could let the user choose a max distance, from which we calculate the filtering border-box.

It is however much more user friendly to do this filtering in a more visual way. The dead-simple option is just show a map, and whatever region the user moves and zooms to, we will list the matching customer. This can be done on a button like google’s “search this area” or fully automatic.

We can also create more complex filtering tools, from drawing a filter circle or rectangle up to a freehand lasso selection.

And we can of course combine civic address filtering with location filtering. For example let the user choose one or more counties and then zoom in to a specific part of the map for a final filter.

Route planning or logging

Once we have a database of client locations we can do interesting things. We’ve already discussed the simpler use-cases, so let’s look at what is beyond looking up who is close by and which clients are in a specific region.

How about visit planning? Let’s say you need to visit a client today. How much time do you need to drive there? One straightforward option is to launch google or other navigation app, with the office/home and client addresses, and let the user continue there.

But, it get’s more interesting if we need to visit multiple clients, and maybe we’d like to optimize which client to visit first. Basically your traveling salesman problem.

Another use-case that requires to calculate traveled distances is employee compensation. For example when an employee is using their personal car for work travel, they are compensated for fuel and amortisation costs. Again, the employee-user can calculate the distances on google maps or watch the odometer carefully. And then the back-office-user has to re-check it again. (We think this is a lot of wasted time, that is why we’ve build the Travel app.)

Again there are many APIs providers that offer these kind of services.

1. Calculating the distance and time for a route with two or more stops. This API is usually called Directions (probably because google called it that first).
2. Calculating the best route through two or more stops. This API is often called Matrix.

• Google Maps API: (There are two versions Routes and Directions-legacy). First 10.000 requests are free).
• Various OSM providers
• OpenRouteService.org (OSM based)

The end of the road

Building address-aware applications is more than just saving a few text fields to the database. Whether you're helping users input accurate data, visualizing that data on a map, or planning optimized visits—it all starts with understanding the nature and complexity of addresses.

We’ve seen that:

• Civic addresses are human-readable but messy, inconsistent, and error-prone.
• Geographic coordinates are exact and machine-friendly, but need to be translated for humans.
• Geocoding and reverse-geocoding services bridge that gap.
• Validation helps reduce user error and improve data quality.
• Location-based filtering can make your app more powerful and intuitive.
• Route planning features unlock new productivity, especially when optimizing multi-stop trips.

Whether your goal is to improve UX, cut down on user support, or build complex logistical features, investing in address intelligence pays off. There’s a rich ecosystem of APIs and data sources out there—from Google and Azure to open solutions like OpenStreetMap—that can help you get started.

Good address handling isn’t just about finding a place—it’s about building smarter, friendlier, and more capable apps.

Happy hacking!