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).
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
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 Geocoder.
We have to deal with
Unlike physical post (office) mail we don't have to deal with
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.
Sun 17 Feb 2019 coverage is:
We are aware of 248 territories We have tests for 248 (100%) territories We have rules for 248 (100%) territories 0 (0%) territories have neither rules nor tests
This output is generated by
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
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.
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").
testcases/countries. The file names correspond to the appropriate ISO 3166-1 alpha-2 code - see
DEas an example).
If in doubt, please get in touch by submitting an issue.
Currently we support the following formatting rules:
replace:regex that operates on the input values, useful for removing bureaucratic cruft like "London Borough of ". Note if you define the regex starting with format X=, for example city= it should operate only on values with that key
postformat_replace:regex that operates on the final output
add_component:with a value of the form
change_country:change the country value of the input, useful for dependent territories. Can include a substitution like
$stateso that that component value is then inserted into the new country value. See
testcases/countries/sh.yamlfor an example.
use_country:use the formating configuration of another country, useful for dependent territories to avoid duplicating configuration
More tests! For every rule about addresses there are exceptions and edge cases to consider. More test cases are always needed.
We welcome your pull requests. Together we can address the world!
This project is licensed under the MIT License - see the LICENSE.txt file for details
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 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.
We also run 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.