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


version 1.99


  # get the templates (or use your own)
  # git clone
  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, });


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

Returns one instance. The conf_path is required.


  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.


  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.

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


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 which includes test cases.

Together we can address the world!


Ed Freyfogle


This software is copyright (c) 2022 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.