parse-address-string

Extract street, city, state, zip, and country components from single-line address string

Usage no npm install needed!

<script type="module">
  import parseAddressString from 'https://cdn.skypack.dev/parse-address-string';
</script>

README

Build Status

parse-address-string

Extract street, city, state, zip, and country components from single-line address string

Example

var parseAddress = require('parse-address-string')

parseAddress('4296 W 7th St, Long Beach, CA 90802', function(err,addressObj){
    console.log('Street: ', addressObj.street_address1)
    console.log('City: ', addressObj.city)
    console.log('State: ', addressObj.state)
    console.log('Zip: ', addressObj.postal_code)
    console.log('Country: ', addressObj.country)
})

Notes

  • This version currently targets US and Canada
    • Many other North American and European countries follow the same standard, but are not explicitly supported in this build
    • Updating lib/*.json would get you 90% of the way there
  • explodeAddress conflates Street1 and Street2 as it is economically difficult to parse with high enough consistency
    • Would require a dictionary of prefix terms ("apt", "ste", etc) with heuristics to ensure it wasn't part of Street1
    • May add support for this in future versions
  • Async callback format is for interoperability with potential future versions of this module, or if you wanted to swap it out with (for example) a call directly to google maps api

Api

parseAddress( addressString, callback )

addressString

callback(err, addressObj)

  • err will always be false in current version, should still check if (err) for future compatibility
  • addressObj has string or NULL properties street_address1, street_address2, city, state, postal_code, country

parseAddress.explodeAddress( addressString, callback )

Same as parseAddress()

parseAddress.implodeAddress( addressObject, callback)

Inverse of explodeAddress

addressObject - Object with some properties street_address1, street_address2, city, state, postal_code, country

callback(err, addressStr)

  • err will always be false in current version, should still check if (err) for future compatibility
  • addressStr Follows inline US/CA address format standard: Street1 Street2, City, State PostalCode, Country*
    *See APA, usps.gov, google maps, etc

Test Cases

See test/test.js for more

// Street address looks like a zip code
parseAddress('90007 W Washington Blvd, Santa Monica, California 90007')
=> {
    street_address1: '90007 W Washington Blvd',
    city: 'Santa Monica',
    state: 'California',
    postal_code: '90007',
    country: null
}

// State with two names spelled out
parseAddress('306 Deep Creek Rd, Fayetteville, North Carolina 28312')
=> {
    street_address1: '306 Deep Creek Rd',
    city: 'Fayetteville',
    state: 'North Carolina',
    postal_code: '28312',
    country: null
}

// Country is appended with comma
parseAddress('1842 W Washington Blvd, Los Angeles, CA 90007, US')
=> {
    street_address1: '1842 W Washington Blvd',
    city: 'Los Angeles',
    state: 'CA',
    postal_code: '90007',
    country: 'US'
}

// Country is appended without comma
parseAddress('1842 W Washington Blvd, Los Angeles, CA 90007 USA')
=> {
    street_address1: '1842 W Washington Blvd',
    city: 'Los Angeles',
    state: 'CA',
    postal_code: '90007',
    country: 'USA'
}

// Canada
parseAddress('646 Union Ave E, Winnipeg, MB R2L 1A4, Canada')
=> {
    street_address1: '646 Union Ave E',
    city: 'Winnipeg',
    state: 'MB',
    postal_code: 'R2L 1A4',
    country: 'Canada'
}

// Canada - no country indicator
parseAddress('229 Begin St W, Thunder Bay, ON P7E 5M5')
=> {
    street_address1: '229 Begin St W',
    city: 'Thunder Bay',
    state: 'ON',
    postal_code: 'P7E 5M5',
    country: null
}

// Street address + city + state only (no postal code)
parseAddress('3300-3332 Glen Koester Ln, Idaho Falls, ID')
=> {
    street_address1: '3300-3332 Glen Koester Ln',
    city: 'Idaho Falls',
    state: 'ID',
    postal_code: null,
    country: null
}

// Street address + city only
parseAddress('757 Juntura-Riverside Rd, Riverside')
=> {
    street_address1: '757 Juntura-Riverside Rd',
    city: 'Riverside',
    state: null,
    postal_code: null,
    country: null
}

// Street address + postal code only
parseAddress('1813 Linda Vista Cir, 92831')
=> {
    street_address1: '1813 Linda Vista Cir',
    city: null,
    state: null,
    postal_code: '92831',
    country: null
}

// Street address only
parseAddress('145 Parkway Ave')
=> {
    street_address1: '145 Parkway Ave',
    city:  null,
    state: null,
    postal_code: null,
    country: null
}

// City only
parseAddress('Los Angeles')
=> {
    street_address1: null,
    city:  'Los Angeles',
    state: null,
    postal_code: null,
    country: null
}

// State only
parseAddress('NJ')
=> {
    street_address1: null,
    city:  null,
    state: 'NJ',
    postal_code: null,
    country: null
}

// Postal code only
parseAddress('13820')
=> {
    street_address1: null,
    city:  null,
    state: null,
    postal_code: '13820',
    country: null
}

// Country only
parseAddress('United States')
=> {
    street_address1: null,
    city:  null,
    state: null,
    postal_code: null,
    country: 'United States'
}

To Do

  • Extract Street2