bitbangx / address-formatter

Universal international address formatter in Javascript

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

Node

npm i @fragaria/address-formatter

// 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'
]
*/

Direct use on webpage

<script type="text/javascript" src="https://unpkg.com/@fragaria/[email protected]"></script>
<script type="text/javascript">
  const formatted = window.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
  */
</script>

Development & Tests

$ git clone [email protected]: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

Making a release

$ 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