npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

address-validator

v0.2.3

Published

Validate street addresses via google's geocoding API. Get back valid addresses with lat/lon coords and a set of inexact matches

Downloads

706

Readme

address-validator

Validate street addresses in nodejs using google geocoding api.

From an input address the lib will return to you a valid address with correct spelling and lat/lon coords, and/or a set of inexact matches that can be used to drive a 'did you mean?' widget.

Currently geared towards North American Addresses but works with all languages.

Install

npm install address-validator

npm

Usage

var addressValidator = require('address-validator');
var Address = addressValidator.Address;
var _ = require('underscore');

//any of the props in this object are optional, also spelling does not have to be exact.
var address = new Address({
    street: '100 North Washington St',
    city: 'Bostont',
    state: 'Mass',
    country: 'US'
});

//the passed in address does not need to be an address object it can be a string. (address objects will give you a better likelihood of finding an exact match)
address = '100 North Washington St, Boston, MA, US';

//`addressValidator.match.streetAddress` -> tells the validator that you think the input should be a street address. This data makes the validator more accurate.
// But, sometimes you dont know.. in that cause you should use `addressValidator.match.unknown`
addressValidator.validate(address, addressValidator.match.streetAddress, function(err, exact, inexact){
    console.log('input: ', address.toString())
    console.log('match: ', _.map(exact, function(a) {
      return a.toString();
    }));
    console.log('did you mean: ', _.map(inexact, function(a) {
      return a.toString();
    }));

    //access some props on the exact match
    var first = exact[0];
    console.log(first.streetNumber + ' '+ first.street);
});

Some example inputs/outputs from above:

input:  12 proctor rd, Massachussetts, US
exact:  []
did you mean:  [ '12 Proctor Road, Chelmsford, MA, US',
  '12 Proctor Road, Townsend, MA, US',
  '12 Proctor Road, Braintree, MA, US',
  '12 Proctor Road, Everett, MA, US',
  '12 Proctor Road, Falmouth, MA, US' ]


input:  100 North Washington St, Boston, MA, US
exact:  [ '100 North Washington Street, Boston, MA, US' ]
did you mean:  []


input:  1 Main St, San Diego, US
address:  []
did you mean:  [ '1 Main Street, San Diego, CA, US' ]

API

addressValidator = require('address-validator');

addressValidator.validate(inputAddr, [addressType, ] cb)

validate an input address.

`inputAddr` - validator.Address object or map with 'street', 'city', 'state', 'country' keys, or string address
`addressType` - validator.match.[key] where key is: streetAddress, route, city, state, country, unknown
        This tells the validator the type of an address you are expecting to validate. default is `validator.match.streetAddress` (you may omit this arg).
`cb`: `function(err, validAddresses, inexactMatches, geocodingResponse)`
    `err` - something went wrong calling the google api
    `validAddresses` - list of Address objects. These are exact matches to your input, and will have proper spelling, caps etc. Its best that you use this instead of what you had
    `inexactMatches` - list of Address objects. Incomplete addresses or addresses that do not match your input address. useful for 'did you mean?' type UIs
    `geocodingResponse` - the json object that i got from google API

addressValidator.setOptions(options)

set address lookup options

`options`: an object containing:
    `countryBias`: more likely to find addresses in this country. Think of this as you where you are searching "from" to find results around you. (use ISO 3166-1 country code)
    `countryMatch`: match results in this country only. (ISO 3166-1 country code)
    `key`: optional google api key (if used will submit requests over https)
    `language`: optional locale to translate the results into, 'DE' for German, etc.
    `proxy`: optional proxy address to pass the request through (`http://<proxy_address>:<proxy_port>`)

proxy note: when used without a key (request via http), the url object submitted with the request adds the value provided to the url.proxy property.

however, when used with a key (request via https), the value is used to create a https-proxy-agent and then added to the url.agent property to properly implement the CONNECT HTTP method.

this is to overcome cases where requests made without a supplied agent are transformed to scramble the request as a security measure, or in configurations that only accept headers specified by RFC7230 (using the CONNECT method). note that using this method ensures the tunneling to work whether these proxy/firewall features are present or not.

addressValidator.Address class

Address object that provides useful methods. Create a new one by
  1. passing a map with these props: {street:'123 main st', city: 'boston', state: 'MA'|'massachussetts', country: 'US'|'United States'}
    None of the props are required, but chances are you wont have a valid address if you omit any of them (except for state)
  2. passing a string containing an address (the address class does not parse the string into parts)
  3. passing a result object from a google geocoding response. ie: geoResponse.results[0]


The validator.validate callback will return to you these objects, except they will have all or some of the following properties:
    streetNumber: '100'
    street: 'North Main St'
    streetAbbr: 'N Main St'
    city: 'Boston'
    state: 'Massachussetts'
    stateAbbr: 'MA'
    country: 'United States'
    countryAbbr: 'US'
    postalCode: 02114
    colloquialArea: '' // e.g. 'Silicon Valley'
    sublocality: '' // e.g. 'Brooklyn'
    location: {lat: 43.233332, lon: 23.2222243}

Methods:
    `toString(useCountryAbbr, useStateAbbr, useStreetAbbr)` - returns a string representing the address. currently geared towards North American addresses
        useCountryAbbr = [optional] default: true - the resulting address string should use country abbr, not the full country name
        useStateAbbr   = [optional] default: true - the resulting address string should use state abbr, not the full state name
        useStreetAbbr  = [optional] default: false - the resulting address string should use street name abbr, not the full street name
        Note: the abbriviated values will only be used if they are available. The Address objects returned to you from the validate callback may have these available.