AddressFormatter

Address formatting for PowerShell using the templates from https://github.com/OpenCageData/address-formatting.

Works cross-platform: PowerShell 5.1 on Windows, PowerShell (pwsh) 7+ on Windows, Linux, and macOS

Based on Perl implementation https://metacpan.org/dist/Geo-Address-Formatter.

Usage

1. Import module
   Import-Module 'c:\your_modules_path\AddressFormatter\AddressFormatter.psd1'
2. Format address using Format-PostalAddress

   $FormatPostAddressOptions = @{
       # Address components as described in https://github.com/OpenCageData/address-formatting/blob/master/conf/components.yaml
       Components = @{
       attention = 'Text for attention line'
       road      = 'Name of the road'
       city      = 'Name of the city'
       postcode  = 'Postcode'
       state     = 'Name of the state'
       country   = 'Name of the country'
    }
   
    # Country as two-letter ISO country code (e.g., "AT", "US") is needed to choose correct address format rules
    Country = 'AT'
   
    # Shorten address components ("St." instead of "Street", "Rd." instead of "Road", etc.)
    #   Depends on Country attribute
    Abbreviate = $false
   
    # Only return known parts of the address, omit unknown parts
    #   When disabled, unknown parts are added the the "attention" component
    OnlyAddress = $false
   
    # Use a custom address template instead of the predefined ones
    #   Predefined templates: https://github.com/OpenCageData/address-formatting/blob/master/conf/countries/worldwide.yaml
    AddressTemplate = $null
   }
   
   Format-PostalAddress @FormatPostAddressOptions

Usage examples

Note the subtle country specific formatting differences in the following examples, such as where the house number and the postcode is placed.

Austrian Presidential Office

$FormatPostAddressOptions = @{
    # Address components as described in https://github.com/OpenCageData/address-formatting/blob/master/conf/components.yaml
    Components = @{
        attention = @(
            'Bürger:innenservice'
            'Österreichische Präsidentschaftskanzlei'
        ) -join [System.Environment]::NewLine
        house        = 'Hofburg'
        house_number = 1
        road         = 'Ballhausplatz'
        city         = 'Wien'
        postcode     = '1010'
        state        = ''
        country      = 'Austria'
    }
    Country    = 'AT'
}

Format-PostalAddress @FormatPostAddressOptions

The PowerShell commands above give the following result:

Bürger:innenservice
Österreichische Präsidentschaftskanzlei
Hofburg
Ballhausplatz 1
1010 Wien
Austria

USA White House

$FormatPostAddressOptions = @{
    # Address components as described in https://github.com/OpenCageData/address-formatting/blob/master/conf/components.yaml
    Components = @{
        house        = 'The White House'
        house_number = 1600
        road         = 'Pennsylvania Avenue, N.W.'
        city         = 'Washington'
        postcode     = '20500'
        state        = 'Washington, DC'
        country      = 'USA'
    }
    Country    = 'US'
}

Format-PostalAddress @FormatPostAddressOptions

The PowerShell commands above give the following result:

The White House
1600 Pennsylvania Avenue, N.W.
Washington, DC 20500
United States of America

Note that the country name 'USA' has been automatically corrected to 'United States of America'.

Admin tasks

Update address templates and test cases

Address templates and test cases are stored in the folder '.\AddressFormatter\address-formatting'. This folder is a git submodule, which is basically a clone of the repository 'https://github.com/OpenCageData/address-formatting'.

To update the templates and test cases, run 'git submodule update'.

Run tests

Run .\tests\tests.ps1 to run the tests. Only errors and a summary will be logged.

Example output:

Import module AddressFormatter
Import module powershell-yaml
Running test cases...
462 test cases from 256 files completed.
  Passed: 462/462 (100,00%)
  Failed: 0/462 (0,00%)