Home

Awesome

address formatting

Overview

This project contains templates and test cases for address formats used in territories around the world. The templates can then be processed in any programming language (see below for list of processors).

Build Status

Build Status

An example:

Given a set of address parts like

 house_number:  17
 road:          Rue du Médecin-Colonel Calbairac
 neighbourhood: Lafourguette
 suburb:        Toulouse Ouest
 postcode:      31000
 city:          Toulouse
 county:        Toulouse
 state:         Midi-Pyrénées
 country:       France
 country_code:  FR

we want to write logic to compile an address in the format consumers expect

17 Rue du Médecin-Colonel Calbairac
31000 Toulouse
France

Why would you want to do this?

The intended use case is database or geocoding systems (forward, reverse, autocomplete) where we know both the country of the address and the language of the user/reader. The address is displayed to a consumer (for example in an app) and not used to print on an envelope for actual postal delivery. We use it to format output from the OpenCage Geocoding API.

Which addresses are we talking about?

We have to deal with

Unlike physical post (office) mail we don't have to deal with

Processing logic

Our goal with this repository is a series of (programming) language independent templates. Those templates can then be processed by whatever software you like.

There are open-source implementations in

We would love more language implementations. The more people who use the templates, the more likely bugs will be reported. If you write a processor, please submit a pull request adding it to the list. Thanks.

International coverage

As of March 2024 coverage is:

We are aware of 251 territories
We have at least one test for 251 (100%) territories
We have rules for 251 (100%) territories
0 (0%) territories have neither rules nor tests

This output is generated by bin/coverage.pl

We need more language specific abbreviations. Please see conf/abbreviations. Pull requests gladly received.

A detailed breakdown of test and configuration coverage can be found by running bin/coverage.pl -d. A list of all known territories is in conf/country_codes.yaml

Please note: the list is simple all officially assigned ISO 3166-1 alpha-2 codes, and is not a political statement on whether or not these territories are or are not or should or should not be political states.

File format

The files are in YAML format. The templates are written in Mustache. Both formats are human readable, strict, solve escaping and support comments. YAML allows references (called "ankers") to avoid copy&paste, Mustache allows sub-templates (called "partials").

How to add your country/territory

  1. edit the .yaml testcase for the country/territory in testcases/countries. The file names correspond to the appropriate ISO 3166-1 alpha-2 code - see conf/country_codes.yaml
  1. edit conf/countries/worldwide.yaml
  1. to test you will now need to process the .yaml test via a processer (see above) and ensure the input leads to the desired output.

If in doubt, please get in touch by submitting an issue.

Formatting rules

Currently we support the following formatting rules:

The future

More tests! For every rule about addresses there are exceptions and edge cases to consider. More test cases are always needed.

Planned features:

We welcome your pull requests. Together we can address the world!

License

This project is licensed under the MIT License - see the LICENSE.txt file for details

Additional resources

If you are working with addresses you may need lists of random addresses/postcodes/coordinates (either in general or for specific countries) for testing.

Further reading on the challenge of address

Here's our blog post anouncing this project and the motivations behind it.

You may enjoy Michael Tandy's Falsehoods Programmers Believe about Addresses.

If it's actual address data you're after, check out OpenStreetMap and OpenAddresses.

If you want to turn longitude, latitude into well formatted addresses or placenames, well that's what a geocoder does. Check out ours: OpenCage Geocoder.

If all this convinces you that address are evil, please check out what3words which allows you to dispense with them entirely.

Who is OpenCage GmbH?

<a href="https://opencagedata.com"><img src="opencage_logo_300_150.png"></a>

We run a worldwide geocoding API and geosearch service based on open data. Learn more about us.

We also organize Geomob, a series of regular meetups for location based service creators, where we do our best to highlight geoinnovation. If you like geo stuff, you will probably enjoy the Geomob podcast.