NAME

Geo::Address::Formatter - take structured address data and format it according to the various global/country rules

VERSION

version 1.84

SYNOPSIS

  #
  # get the templates (or use your own)
  # git clone git@github.com:OpenCageData/address-formatting.git
  #
  my $GAF = Geo::Address::Formatter->new( conf_path => '/path/to/templates' );
  my $components = { ... }
  my $text = $GAF->format_address($components, { country => 'FR' } );
  my $rh_final_components = $GAF->final_components();
  #
  # or if we want shorter output
  # 
  my $short_text = $GAF->format_address($components, { country => 'FR', abbreviate => 1, });

new

  my $GAF = Geo::Address::Formatter->new( conf_path => '/path/to/templates' );

Returns one instance. The conf_path is required.

final_components

  my $rh_components = $GAF->final_components();

returns a reference to a hash of the final components that are set at the completion of format_address. Warns if called before they have been set.

format_address

  my $text = $GAF->format_address(\%components, \%options );

Given a structures address (hashref) and options (hashref) returns a formatted address.

Possible options you are:

    'country', which should be an uppercase ISO 3166-1:alpha-2 code
    e.g. 'GB' for Great Britain, 'DE' for Germany, etc.
    If ommited we try to find the country in the address components.

    'abbreviate', if supplied common abbreviations are applied
    to the resulting output.

DESCRIPTION

You have a structured postal address (hash) and need to convert it into a readable address based on the format of the address country.

For example, you have:

  {
    house_number => 12,
    street => 'Avenue Road',
    postcode => 45678,
    city => 'Deville'
  }

you need:

  Great Britain: 12 Avenue Road, Deville 45678
  France: 12 Avenue Road, 45678 Deville
  Germany: Avenue Road 12, 45678 Deville
  Latvia: Avenue Road 12, Deville, 45678

It gets more complicated with 200+ countries and territories and dozens more address components to consider.

This module comes with a minimal configuration to run tests. Instead of developing your own configuration please use (and contribute to) those in https://github.com/OpenCageData/address-formatting which includes test cases.

Together we can address the world!

AUTHOR

Ed Freyfogle

COPYRIGHT AND LICENSE

This software is copyright (c) 2020 by Opencage GmbH.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Geo::Address::Formatter

perl -MCPAN -e shell
install Geo::Address::Formatter