=encoding utf8

=head1 NAME

Geo::libpostal - Perl bindings for libpostal

=head1 SYNOPSIS

  use Geo::libpostal ':all';

  # normalize an address
  my @addresses = expand_address('120 E 96th St New York');

  # parse addresses into their components
  my %address = parse_address('The Book Club 100-106 Leonard St Shoreditch London EC2A 4RH, United Kingdom');

  # %address contains:
  # (
  #   road         => 'leonard st',
  #   postcode     => 'ec2a 4rh',
  #   house        => 'the book club',
  #   house_number => '100-106',
  #   suburb       => 'shoreditch',
  #   country      => 'united kingdom',
  #   city         => 'london'
  # );

=head1 DESCRIPTION

libpostal is a C library for parsing/normalizing international street addresses. Address strings can be normalized using C<expand_address> which returns a list of valid variations so you can check for duplicates in your dataset. It supports normalization in over L<60 languages|https://github.com/openvenues/libpostal/tree/master/resources/dictionaries>. An address string can also be parsed into its constituent parts using C<parse_address> such as house name, number, city and postcode.

=head1 FUNCTIONS

=head2 expand_address

  use Geo::libpostal 'expand_address';

  my @ny_addresses = expand_address('120 E 96th St New York');
  my @fr_addresses = expand_address('Quatre vingt douze R. de l\'Église');

Takes an address string and returns a list of known variants. Useful for
normalization. Accepts many boolean options:

  expand_address('120 E 96th St New York',
      latin_ascii => 1,
      transliterate => 1,
      strip_accents => 1,
      decompose => 1,
      lowercase => 1,
      trim_string => 1,
      drop_parentheticals => 1,
      replace_numeric_hyphens => 1,
      delete_numeric_hyphens => 1,
      split_alpha_from_numeric => 1,
      replace_word_hyphens => 1,
      delete_word_hyphens => 1,
      delete_final_periods => 1,
      delete_acronym_periods => 1,
      drop_english_possessives => 1,
      delete_apostrophes => 1,
      expand_numex => 1,
      roman_numerals => 1,
  );

B<Warning>: libpostal L<segfaults|https://github.com/openvenues/libpostal/issues/79> if all options are set to false. Also accepts an arrayref of language codes per L<ISO 639-1|https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes>:

 expand_address('120 E 96th St New York', languages => [qw(en fr)]);

This is useful if you are normalizing addresses in multiple languages.

Will C<die> on C<undef> and empty addresses, odd numbers of options and
unrecognized options. Exported on request.

=head2 parse_address

  use Geo::libpostal 'parse_address';

  my %ny_address = parse_address('120 E 96th St New York');
  my %fr_address = parse_address('Quatre vingt douze R. de l\'Église');


=cut

=pod

Will C<die> on C<undef> and empty addresses. Exported on request.

C<parse_address()> may return L<duplicate labels|https://github.com/openvenues/libpostal/issues/27> for invalid addresses
strings.

=head1 WARNING

libpostal uses C<setup()> and C<teardown()> functions. Setup is lazily loaded. Teardown occurs in an C<END> block automatically. C<Geo::libpostal> will C<die> if C<expand_address> or C<parse_address> is called after teardown.

=head1 EXTERNAL DEPENDENCIES

L<libpostal|https://github.com/openvenues/libpostal> is required.

=head1 INSTALLATION

You can install this module with CPAN:

  $ cpan Geo::libpostal

Or clone it from GitHub and install it manually:

  $ git clone https://github.com/dnmfarrell/Geo-libpostal
  $ cd Geo-libpostal
  $ perl Makefile.PL
  $ make
  $ make test
  $ make install

=head1 AUTHOR

E<copy> 2016 David Farrell

=head1 LICENSE

See LICENSE


=cut