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


version 1.9982


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

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.


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


  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


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