/ 
Geo-Address-Formatter-1.9990
River stage zero No dependents
/ Geo::Address::Formatter

NAME

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

VERSION

version 1.9990

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 output will only contain known address components (will not include POI names). Can be overridden per-call via the only_address option to "format_address".

final_components

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

Returns a reference to a hash of the final components that were set during the most recent call to format_address. Returns undef if called before format_address has been called. Warns in that case unless no_warnings was set at object creation.

format_address

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

Given structured address components (hashref) and options (hashref) returns a formatted address as a multiline string with a trailing newline.

Possible options are:

  • abbreviate

    If true, 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

    An uppercase ISO 3166-1 alpha-2 code, e.g. 'GB' for Great Britain, 'DE' for Germany, etc. If omitted the country is determined from the address components.

  • only_address

    Same as the only_address constructor option but applied per-call.

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!

SEE ALSO

https://github.com/OpenCageData/address-formatting - the address formatting template configuration used by this module.

https://opencagedata.com - OpenCage geocoder.

AUTHOR

Ed Freyfogle

COPYRIGHT AND LICENSE

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