postal

README

gopostal

Go/cgo interface to libpostal, a C library for fast international street address parsing and normalization.

Usage

To expand address strings into normalized forms suitable for geocoder queries:

package main

import (
  "fmt"

  "github.com/13k/gopostal/expand"
)

func main() {
  if err := expand.Setup(); err != nil {
    panic(err)
  }

  expansions := expand.ExpandAddress("Quatre-vingt-douze Ave des Ave des Champs-Élysées")

  for i := 0; i < len(expansions); i++ {
    fmt.Println(expansions[i])
  }
}

To parse addresses into components:

package main

import (
  "fmt"

  "github.com/13k/gopostal/parser"
)

func main() {
  if err := parser.Setup(); err != nil {
    panic(err)
  }

  parsed := parser.ParseAddress("781 Franklin Ave Crown Heights Brooklyn NY 11216 USA")

  fmt.Println(parsed)
}

Prerequisites

Before using the Go bindings, you must install the libpostal C library. Make sure you have the following prerequisites:

On Ubuntu/Debian

sudo apt-get install curl autoconf automake libtool pkg-config

On CentOS/RHEL

sudo yum install curl autoconf automake libtool pkgconfig

On Mac OSX

sudo brew install curl autoconf automake libtool pkg-config

Installing libpostal

git clone https://github.com/openvenues/libpostal
cd libpostal
./bootstrap.sh
./configure --datadir=[...some dir with a few GB of space...]
make
sudo make install

# On Linux it's probably a good idea to run
sudo ldconfig

Installation

For expansions:

go get github.com/openvenues/gopostal/expand

For parsing:

go get github.com/openvenues/gopostal/parser

Tests

go test github.com/openvenues/gopostal/...

Documentation

Index

• Constants
• func ExpandAddress(address string) []string
• func ExpandAddressOptions(address string, options ExpandOptions) []string
• func Setup() error
• func SetupClassifier() error
• func SetupClassifierDataDir(dir string) error
• func SetupDataDir(dir string) error
• func SetupParser() error
• func SetupParserDataDir(dir string) error
• func Teardown()
• func TeardownClassifier()
• func TeardownParser()
• func Version() string
• type AddressComponent
• type ExpandOptions
  • func DefaultExpandOptions() ExpandOptions
• type ParsedComponent
  • func ParseAddress(address string) []ParsedComponent
  • func ParseAddressOptions(address string, options ParserOptions) []ParsedComponent
• type ParserOptions
  • func DefaultParserOptions() ParserOptions

Constants

const (
	AddressComponentNone        = AddressComponent(C.LIBPOSTAL_ADDRESS_NONE)
	AddressComponentAny         = AddressComponent(C.LIBPOSTAL_ADDRESS_ANY)
	AddressComponentName        = AddressComponent(C.LIBPOSTAL_ADDRESS_NAME)
	AddressComponentHouseNumber = AddressComponent(C.LIBPOSTAL_ADDRESS_HOUSE_NUMBER)
	AddressComponentStreet      = AddressComponent(C.LIBPOSTAL_ADDRESS_STREET)
	AddressComponentUnit        = AddressComponent(C.LIBPOSTAL_ADDRESS_UNIT)
	AddressComponentLevel       = AddressComponent(C.LIBPOSTAL_ADDRESS_LEVEL)
	AddressComponentStaircase   = AddressComponent(C.LIBPOSTAL_ADDRESS_STAIRCASE)
	AddressComponentEntrance    = AddressComponent(C.LIBPOSTAL_ADDRESS_ENTRANCE)
	AddressComponentCategory    = AddressComponent(C.LIBPOSTAL_ADDRESS_CATEGORY)
	AddressComponentNear        = AddressComponent(C.LIBPOSTAL_ADDRESS_NEAR)
	AddressComponentToponym     = AddressComponent(C.LIBPOSTAL_ADDRESS_TOPONYM)
	AddressComponentPostalCode  = AddressComponent(C.LIBPOSTAL_ADDRESS_POSTAL_CODE)
	AddressComponentPoBox       = AddressComponent(C.LIBPOSTAL_ADDRESS_PO_BOX)
	AddressComponentAll         = AddressComponent(C.LIBPOSTAL_ADDRESS_ALL)
)

Functions

func ExpandAddress

func ExpandAddress(address string) []string

ExpandAddress expands an address (using libpostal_expand_address) with default options.

func ExpandAddressOptions

func ExpandAddressOptions(address string, options ExpandOptions) []string

ExpandAddressOptions expands an address (using libpostal_expand_address) with custom options.

func Setup

func Setup() error

Setup initializes libpostal using default data directory (defined at libpostal's compile-time).

func SetupClassifier

func SetupClassifier() error

SetupClassifier initializes the language classifier using default data directory (defined at libpostal's compile-time).

func SetupClassifierDataDir

func SetupClassifierDataDir(dir string) error

SetupClassifierDataDir initializes the language classifier using a custom data directory.

func SetupDataDir

func SetupDataDir(dir string) error

SetupDataDir initializes libpostal using a custom data directory.

func SetupParser

func SetupParser() error

SetupParserDataDir initializes the address parser using a custom data directory.

func SetupParserDataDir

func SetupParserDataDir(dir string) error

SetupParserDataDir initializes the address parser using a custom data directory.

func Teardown

func Teardown()

Teardown frees all resources allocated by Setup or SetupDataDir.

func TeardownClassifier

func TeardownClassifier()

TeardownClassifier frees all resources allocated by SetupClassifier or SetupClassifierDataDir.

func TeardownParser

func TeardownParser()

TeardownParser frees all resources allocated by SetupParser or SetupParserDataDir.

func Version

func Version() string

Types

type AddressComponent

type AddressComponent uint16

type ExpandOptions

type ExpandOptions struct {
	Languages              []string
	AddressComponents      AddressComponent
	LatinASCII             bool
	Transliterate          bool
	StripAccents           bool
	Decompose              bool
	Lowercase              bool
	TrimString             bool
	ReplaceWordHyphens     bool
	DeleteWordHyphens      bool
	ReplaceNumericHyphens  bool
	DeleteNumericHyphens   bool
	SplitAlphaFromNumeric  bool
	DeleteFinalPeriods     bool
	DeleteAcronymPeriods   bool
	DropEnglishPossessives bool
	DeleteApostrophes      bool
	ExpandNumex            bool
	RomanNumerals          bool
}

ExpandOptions are the options used with ExpandAddressOptions.

func DefaultExpandOptions

func DefaultExpandOptions() ExpandOptions

DefaultExpandOptions returns the default ParserOptions.

type ParsedComponent

type ParsedComponent struct {
	Label string `json:"label"`
	Value string `json:"value"`
}

ParsedComponent represents a parsed address component returned by ParseAddress* functions.

func ParseAddress

func ParseAddress(address string) []ParsedComponent

ParseAddress parses an address (using libpostal_parse_address) with default options.

func ParseAddressOptions

func ParseAddressOptions(address string, options ParserOptions) []ParsedComponent

ParseAddressOptions parses an address (using libpostal_parse_address) with custom options.

type ParserOptions

type ParserOptions struct {
	Language string
	Country  string
}

ParserOptions are the options used with ParserAddressOptions.

func DefaultParserOptions

func DefaultParserOptions() ParserOptions

DefaultParserOptions returns the default ParserOptions.