addrFmt

README

Golang Address Formatter

This Address Formatter package is able to convert an address into many international formats of postal addresses based on OpenCage Configuration (or custom ones). You can use the provided address structure or use a map of address components.

Usage

Import

import (
    "fmt"
    "github.com/timonmasberg/address-formatter"
)

Set up your config files or use OpenCage Configuration (/conf)
Load config from config files:

config := addrFmt.LoadConfig(addrFmt.ConfigFiles{
            CountriesPath:     "templates/countries/worldwide.yaml",
            ComponentsPath:    "templates/components.yaml",
            StateCodesPath:    "templates/state_codes.yaml",
            CountryToLangPath: "templates/country2lang.yaml",
            CountyCodesPath:   "templates/county_codes.yaml",
            CountryCodesPath:  "templates/country_codes.yaml",
            AbbreviationFiles: "templates/abbreviations/*.yaml",
        })

You can choose between 3 output formats:

1. Array (returns a slice where each entry represents an address component)
2. OneLine (address components joined with a comma in one line)
3. PostalFormat (valid postal format for letters etc with a trailing \n)

config.OutputFormat = addrFmt.PostalFormat

address :=  &addrFmt.Address{
    House:         "Bundestag",
    HouseNumber:   "1",
    Road:          "Platz der Republik",
    City:          "Berlin",
    Postcode:      "11011",
    State:         "Berlin",
    Country:       "Deutschland",
}

formattedAddress, err := addrFmt.FormatAddress(address, config)
if err != nil {
    fmt.Printf("Failed to format address: %v", err)
} else {
    fmt.Println(formattedAddress)
    /*
        Bundestag
        Platz der Republik 1
        11011 Berlin
        Deutschland
    */
}

If you have data from sources such as OSM you probably have a map of unknown data. This package can cleanup the map by using data from the configurations and turn it into an Address structure. You can also use MapToAddress directly if you are aware of the quality. Just make sure you add your component names to the component aliases as this package uses the names from OpenCageData.

    	// with unknown data such as from osm
addressMap := make(map[string]string)
addressMap["house"] = "Bundestag"
addressMap["house_number"] = "1"
addressMap["road"] = "Platz der Republik"
addressMap["postcode"] = "11011"
addressMap["state"] = "Berlin"
addressMap["country"] = "Deutschland"

address, err = addrFmt.GetFixedAddress(addressMap, config)
if err != nil {
    fmt.Printf("Fixing address failed: %v", err)
}

If you want to treat every unknown component name as an attention entry, set UnknownAsAttention to true

config.UnknownAsAttention = true

addressMap["mutti"] = "Angela Merkel"
addressMap["vati"] = "Frank-Walter Steinmeier"

address, err = addrFmt.GetFixedAddress(addressMap, config)
if err != nil {
    fmt.Printf("Fixing address failed: %v", err)
} else {
    fmt.Println(address.Attention)
    // Angela Merkel, Frank-Walter Steinmeier
}

Abbreviations tbd.

Testing

Load the config files from the submodule with copy-templates.cmd. Testing the formatter relies on testcase files. You can execute copy-testcases.cmd to use the OpenCageData testcases, or you can run the tests with your own. Just create them in the testcases folder with the same structure.

License

MIT

Documentation

Index

• func FormatAddress(address *Address, config *Config) (interface{}, error)
• type Address
  • func GetFixedAddress(addressMap addressMap, config *Config) (*Address, error)
  • func MapToAddress(addressMap map[string]string, componentAliases map[string]componentAlias, ...) *Address
• type Config
  • func LoadConfig(configFiles ConfigFiles) *Config
• type ConfigFiles
• type OutputFormat

Functions

func FormatAddress

func FormatAddress(address *Address, config *Config) (interface{}, error)

FormatAddress formats an Address object based on it

Types

type Address

type Address struct {
	Attention     string
	House         string
	HouseNumber   string
	Road          string
	Hamlet        string
	Village       string
	Neighbourhood string
	PostalCity    string
	City          string
	CityDistrict  string
	Municipality  string
	County        string
	CountyCode    string
	StateDistrict string
	Postcode      string
	State         string
	StateCode     string
	Region        string
	Suburb        string
	Quarter       string
	Residential   string
	Town          string
	Island        string
	Archipelago   string
	Country       string
	CountryCode   string
	Continent     string
}

func GetFixedAddress

func GetFixedAddress(addressMap addressMap, config *Config) (*Address, error)

GetFixedAddress Fixes postcode/country, adds missing state/county/country-code and applies template replacements GetFixedAddress Entrypoint for data such as from osm

func MapToAddress

func MapToAddress(addressMap map[string]string, componentAliases map[string]componentAlias, unknownAsAttention bool) *Address

MapToAddress Convert map of address components used in OpenCageData templates and their aliases into an Address struct

type Config

type Config struct {
	ComponentAliases   map[string]componentAlias
	Templates          map[string]template
	StateCodes         map[string]map[string]interface{}
	CountryToLang      map[string]interface{}
	CountyCodes        map[string]map[string]interface{}
	CountryCodes       map[string]string
	Abbreviations      map[string]abbreviation
	Abbreviate         bool
	UnknownAsAttention bool
	OutputFormat       OutputFormat
}

func LoadConfig

func LoadConfig(configFiles ConfigFiles) *Config

LoadConfig parses the configuration files into a Config structure

type ConfigFiles

type ConfigFiles struct {
	CountriesPath     string
	ComponentsPath    string
	StateCodesPath    string
	CountryToLangPath string
	CountyCodesPath   string
	CountryCodesPath  string
	AbbreviationFiles string
}

type OutputFormat

type OutputFormat int

const (
	Array        OutputFormat = iota
	OneLine      OutputFormat = iota
	PostalFormat OutputFormat = iota
)