https://github.com/fragaria/address-formatter
Universal international address formatter in Javascript
https://github.com/fragaria/address-formatter
addresses formatting i18n
Last synced: 6 months ago
JSON representation
Universal international address formatter in Javascript
- Host: GitHub
- URL: https://github.com/fragaria/address-formatter
- Owner: fragaria
- License: mit
- Created: 2019-02-14T19:53:08.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2025-12-26T13:00:14.000Z (6 months ago)
- Last Synced: 2025-12-28T00:59:07.809Z (6 months ago)
- Topics: addresses, formatting, i18n
- Language: JavaScript
- Size: 5.69 MB
- Stars: 106
- Watchers: 3
- Forks: 21
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# JS Address formatter
[](https://coveralls.io/github/fragaria/address-formatter?branch=master)
Based on an amazing work of [OpenCage Data](https://github.com/OpenCageData/address-formatting/)
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](https://wiki.openstreetmap.org/wiki/Nominatim)
in the `address` field. Other compatible sources of data
such as [Photon](https://photon.komoot.io/) 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
```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'
]
*/
```
### Direct use on webpage
```html
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
*/
```
## 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
```
### Making a release
```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](https://github.com/OpenCageData/address-formatting/)
with a minimal localized test-case.
# Acknowledgments
Grat many thanks to these implementations:
- [Perl](https://github.com/OpenCageData/perl-Geo-Address-Formatter)
- [PHP](https://github.com/predicthq/address-formatter-php)