Miss any of our Open RFC calls?Watch the recordings here! »

@fragaria/address-formatter

2.2.1 • Public • Published

JS Address formatter

Greenkeeper badge Coverage Status Build Status

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
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 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",
}, {
  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/address-formatter@1.0.0"></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 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

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:

Install

npm i @fragaria/address-formatter

DownloadsWeekly Downloads

1,057

Version

2.2.1

License

MIT

Unpacked Size

848 kB

Total Files

18

Last publish

Collaborators

  • avatar