PHPackages predicthq/address-formatter-templates - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. predicthq/address-formatter-templates AbandonedArchivedLibrary[Utility & Helpers](/categories/utility) predicthq/address-formatter-templates ===================================== Address formatter templates from https://github.com/OpenCageData/address-formatting - used with the predicthq/address-formatter package. v1.0.0(10y ago)4182.5k↑18.8%42MITPerl Since Apr 28Pushed 7y ago4 watchersCompare [ Source](https://github.com/predicthq/address-formatter-templates)[ Packagist](https://packagist.org/packages/predicthq/address-formatter-templates)[ RSS](/packages/predicthq-address-formatter-templates/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (1)DependenciesVersions (2)Used By (2) [![Build Status](https://camo.githubusercontent.com/dc5baf8928db92a116f67b540b544112e23343fa9c0916fa8c800ac080d3c774/68747470733a2f2f7472617669732d63692e6f72672f4f70656e43616765446174612f616464726573732d666f726d617474696e672e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/OpenCageData/address-formatting) address formatting ================== [](#address-formatting) ### A quick example [](#a-quick-example) Given a set of address parts ``` 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 ``` you want to write logic to compile addresses in the format consumers expect ``` 17 Rue du Médecin-Colonel Calbairac 31000 Toulouse France ``` or perhaps simply ``` Rue du Médecin-Colonel Calbairac Toulouse France ``` This repository contains templates for various address formats used in territories around the world. It also contains test cases. ### Which addresses we're talking about [](#which-addresses-were-talking-about) 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](https://opencagedata.com). We have to deal with - incomplete data - anything with a name (peaks, bridges, bus stops) Unlike [physical post (office) mail](http://www.bitboost.com/ref/international-address-formats.html) we don't have to deal with - apartment/flat number, floor numbers - PO boxes - translating the language of the (destination) address. Whatever language is input is output. ### Processing logic [](#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. We've written, use and maintain a working implementation of a processer in Perl, see (CPAN: [Geo::Address::Formatter](https://metacpan.org/release/Geo-Address-Formatter), [github repo](https://github.com/opencagedata/perl-Geo-Address-Formatter)). There is also an open-source [implementation in PHP](https://github.com/predicthq/address-formatter-php). We would love there to be other langauge implementations. If you do write a processor, please let us know so we can list it here. ### Coverage [](#coverage) As of `Sat 25 Mar 2017` coverage is: ``` We are aware of 248 territories We have tests for 250 (100%) territories We have rules for 249 (100%) territories 0 (0%) territories have neither rules nor tests ``` We need more language specific abbreviations, please see `conf/abbreviations` 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` Note: the list is simple all officially assigned [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements), 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 [](#file-format) The files are in [YAML](http://yaml.org/) format. The templates are written in [Mustache](http://mustache.github.io/). 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 [](#how-to-add-your-countryterritory) 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` - a good way to get sample data is: - find an addressed location (house, business, etc) in your target territory in OpenStreetMap - get the coordinates (lat, long) of the location - put the coordinates into the [OpenCage Geocoder demo page](https://opencagedata.com/demo) - look at the resulting JSON in the *Raw Response* tab 2. edit `conf/countries/worldwide.yaml` - Possibly your country/territory uses an existing generic format as defined at the top of the file. If so, great, just map you country\_code to the generic template. You may still want to add clean up code (see the entry for `DE` as an example). - If not you need to define a new generic rule set - possibly you will need to define new state/region mappings in `conf/state_codes.yaml` 3. 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 via github issues. ### Formatting rules [](#formatting-rules) 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 `component=XXXX` - `change_country:` change the country value of the input, useful for dependent territories. Can include a substitution like `$state` so that that component value is then inserted into the new country value. See `testcases/countries/sh.yaml` for an example. - `use_country:` use the formating configuration of another country, useful for dependent territories to avoid duplicating configuration ### The future [](#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 - basic error checking, for example ignore things which obviously can not be postcodes - define rules for postcode format specifically We welcome your pull requests. Together we can address the world! ### Who are we? [](#who-are-we) We run the [OpenCage Geocoder](https://opencagedata.com). We also run [\#geomob](http://geomobldn.org), a meetup of London location based service developers where we do our best to highlight geoinnovation. ### Further reading [](#further-reading) Here's [our blog post anouncing this project](https://blog.opencagedata.com/post/99059889253/good-looking-addresses-solving-the-berlin-berlin) and the motivations behind it. You may enjoy Michael Tandy's [Falsehoods Programmers Believe about Addresses](http://www.mjt.me.uk/posts/falsehoods-programmers-believe-about-addresses/). If it's actual address data you're after, check out [OpenAddresses](http://openaddresses.io/). 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](https://opencagedata.com). If all this convinces you that address are evil, please check out [what3words](http://what3words.com) which allows you to dispense with them entirely. ### Health Score 39 — LowBetter than 86% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity38 Limited adoption so far Community24 Small or concentrated contributor base Maturity63 Established project with proven stability Bus Factor1 Top contributor holds 74.4% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 3672d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/b156736f0655f024b987fe25fd0cab6f557d79324673acb9b5bf4638e8367100?d=identicon)[predicthq](/maintainers/predicthq) --- Top Contributors [![freyfogle](https://avatars.githubusercontent.com/u/351074?v=4)](https://github.com/freyfogle "freyfogle (354 commits)")[![albarrentine](https://avatars.githubusercontent.com/u/238455?v=4)](https://github.com/albarrentine "albarrentine (83 commits)")[![mtmail](https://avatars.githubusercontent.com/u/3727288?v=4)](https://github.com/mtmail "mtmail (16 commits)")[![Flimm](https://avatars.githubusercontent.com/u/355454?v=4)](https://github.com/Flimm "Flimm (10 commits)")[![GaretJax](https://avatars.githubusercontent.com/u/86236?v=4)](https://github.com/GaretJax "GaretJax (3 commits)")[![mar-v-in](https://avatars.githubusercontent.com/u/994036?v=4)](https://github.com/mar-v-in "mar-v-in (3 commits)")[![robertkern](https://avatars.githubusercontent.com/u/2150042?v=4)](https://github.com/robertkern "robertkern (3 commits)")[![SarahNazzari](https://avatars.githubusercontent.com/u/17162204?v=4)](https://github.com/SarahNazzari "SarahNazzari (1 commits)")[![danstowell](https://avatars.githubusercontent.com/u/202965?v=4)](https://github.com/danstowell "danstowell (1 commits)")[![darksmo](https://avatars.githubusercontent.com/u/1516659?v=4)](https://github.com/darksmo "darksmo (1 commits)")[![ldvc](https://avatars.githubusercontent.com/u/5823358?v=4)](https://github.com/ldvc "ldvc (1 commits)") --- Tags addresstemplatespredicthq ### Embed Badge ![Health badge](/badges/predicthq-address-formatter-templates/health.svg) ``` [![Health](https://phpackages.com/badges/predicthq-address-formatter-templates/health.svg)](https://phpackages.com/packages/predicthq-address-formatter-templates) ``` ### Alternatives [markrogoyski/ipv4-subnet-calculator Network calculator for subnet mask and other classless (CIDR) network information. 177813.7k6](/packages/markrogoyski-ipv4-subnet-calculator)[sylius/addressing-bundle Addressing and zone management for Symfony applications. 33221.4k3](/packages/sylius-addressing-bundle)[tapp/filament-google-autocomplete-field Filament plugin that provides a Google Autocomplete field 3098.1k](/packages/tapp-filament-google-autocomplete-field)[flyingluscas/viacep-php ViaCEP PHP SDK 3640.2k](/packages/flyingluscas-viacep-php)[yieldstudio/nova-google-autocomplete A Laravel Nova Google autocomplete field. 12218.4k](/packages/yieldstudio-nova-google-autocomplete)[nonsapiens/realaddressfactory Creates real-world street addresses from Google Maps, to use in database seeding, unit tests, or anything else. Supports Laravel 11+, and Faker 4910.2k7](/packages/nonsapiens-realaddressfactory) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)