NAME

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

VERSION

version 1.9982

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.

Optional parameters are:

debug: prints tons of debugging info for use in development.

no_warnings: turns off a few warnings if configuration is not optimal.

only_address: formatted will only contain known components (will not include POI names). Note, can be overridden with optional param to format_address method.

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 (unless no_warnings was set at object creation).

format_address

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

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

Possible options are:

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

    'address_template', a mustache format template to be used instead of the template
    defined in the configuration

    '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.

    'only_address', same as only_address global option but set at formatting level

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) 2023 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