JS Address formatter


Based on an amazing work of OpenCage Data
who collected so many international formats of postal addresses, this is a Javascript implementation
of that formatter.

This library can format almost anything that comes out of
Open Street Maps' Nominatim API
in the address field. Other compatible sources of data
such as Photon might be used as well.

It can automatically detect the country's
formatting customs, but allows you to *pick a specific country
format*. Furthermore, it allows you to abbreviate the common names,
such as Avenue or Road.

The formatting specification for the whole world is part of
the distribution package, there is currently no plan to prepare
smaller builds with limited area coverage.

Installation & Usage

$3

``sh
npm i @fragaria/address-formatter
`

`js
// import addressFormatter from '@fragaria/address-formatter';
const addressFormatter = require('@fragaria/address-formatter');

// Basic examples
const formatted = addressFormatter.format({
"houseNumber": 301,
"road": "Hamilton Avenue",
"neighbourhood": "Crescent Park",
"city": "Palo Alto",
"postcode": 94303,
"county": "Santa Clara County",
"state": "California",
"country": "United States of America",
"countryCode": "US",
});
/*
301 Hamilton Avenue
Palo Alto, CA 94303
United States of America
*/
const formattedWithAppendedCountry = addressFormatter.format({
"houseNumber": 301,
"road": "Hamilton Avenue",
"neighbourhood": "Crescent Park",
"city": "Palo Alto",
"postcode": 94303,
"county": "Santa Clara County",
"state": "California",
"countryCode": "US",
}, {
appendCountry: true
});
/*
301 Hamilton Avenue
Palo Alto, CA 94303
United States of America
*/

// You can overwrite the country code incoming from the map service
const abbreviatedUkFormat = addressFormatter.format({
"houseNumber": 301,
"road": "Hamilton Avenue",
"neighbourhood": "Crescent Park",
"city": "Palo Alto",
"postcode": 94303,
"county": "Santa Clara County",
"state": "California",
"country": "United States of America",
"countryCode": "US",
}, {
abbreviate: true,
countryCode: 'UK'
});
/*
301 Hamilton Ave
Palo Alto
94303
USA
*/

// You can use a fallback to keep the library working when the country code is wrong
const fallbackCountryCode = addressFormatter.format({
"houseNumber": 301,
"road": "Hamilton Avenue",
"neighbourhood": "Crescent Park",
"city": "Palo Alto",
"postcode": 94303,
"county": "Santa Clara County",
"state": "California",
"country": "United States of America",
"countryCode": "yu",
}, {
abbreviate: true,
fallbackCountryCode: 'UK'
});
/*
301 Hamilton Ave
Palo Alto
94303
USA
*/

// You can get the address as a list of lines to make your formatting easier
const formattedAsLines = addressFormatter.format({
"houseNumber": 301,
"road": "Hamilton Avenue",
"neighbourhood": "Crescent Park",
"city": "Palo Alto",
"postcode": 94303,
"county": "Santa Clara County",
"state": "California",
"country": "United States of America",
"countryCode": "US",
}, {
output: 'array'
});
/*
[
'301 Hamilton Avenue',
'Palo Alto, CA 94303',
'United States of America'
]
*/
`

$3

`html


`

Development & Tests

`sh
$ git clone git@github.com:fragaria/address-formatter.git
$ cd address-formatter


Install the proper NodeJS

$ nvm install

Download the /OpenCageData/address-formatting/ spec

$ npm run pull-submodules

Install dependencies

$ npm install

Generate JS-friendly spec

$ npm run prepare-templates

Run the tests

$ npm test
`

$3

`sh
$ npm version X.Y.Z
$ git push origin master && git push origin vX.Y.Z
``

And the CI server takes care of the rest

Help needed

All pull requests are definitely welcome. If an address
is badly formatted, submit PRs directly to the
original repository
with a minimal localized test-case.

Acknowledgments

Grat many thanks to these implementations:

- Perl
- PHP