<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">=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         =&gt; 'leonard st',
  #   postcode     =&gt; 'ec2a 4rh',
  #   house        =&gt; 'the book club',
  #   house_number =&gt; '100-106',
  #   suburb       =&gt; 'shoreditch',
  #   country      =&gt; 'united kingdom',
  #   city         =&gt; 'london'
  # );

=head1 DESCRIPTION

libpostal is a C library for parsing/normalizing international street addresses. Address strings can be normalized using C&lt;expand_address&gt; which returns a list of valid variations so you can check for duplicates in your dataset. It supports normalization in over L&lt;60 languages|https://github.com/openvenues/libpostal/tree/master/resources/dictionaries&gt;. An address string can also be parsed into its constituent parts using C&lt;parse_address&gt; 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 =&gt; 1,
      transliterate =&gt; 1,
      strip_accents =&gt; 1,
      decompose =&gt; 1,
      lowercase =&gt; 1,
      trim_string =&gt; 1,
      drop_parentheticals =&gt; 1,
      replace_numeric_hyphens =&gt; 1,
      delete_numeric_hyphens =&gt; 1,
      split_alpha_from_numeric =&gt; 1,
      replace_word_hyphens =&gt; 1,
      delete_word_hyphens =&gt; 1,
      delete_final_periods =&gt; 1,
      delete_acronym_periods =&gt; 1,
      drop_english_possessives =&gt; 1,
      delete_apostrophes =&gt; 1,
      expand_numex =&gt; 1,
      roman_numerals =&gt; 1,
  );

B&lt;Warning&gt;: old versions of libpostal L&lt;segfault|https://github.com/openvenues/libpostal/issues/79&gt; if all options are set to false. C&lt;Geo::libpostal&gt; includes a unit test for this.

Also accepts an arrayref of language codes per L&lt;ISO 639-1|https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes&gt;:

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

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

Finally C&lt;expand_address&gt; accepts an option for which address C&lt;components&gt; to expand. This is a 16 bit integer bitmask. These constants are exported with the C&lt;:all&gt; tag:

  $ADDRESS_NONE
  $ADDRESS_ANY
  $ADDRESS_NAME
  $ADDRESS_HOUSE_NUMBER
  $ADDRESS_STREET
  $ADDRESS_UNIT
  $ADDRESS_LOCALITY
  $ADDRESS_ADMIN1
  $ADDRESS_ADMIN2
  $ADDRESS_ADMIN3
  $ADDRESS_ADMIN4
  $ADDRESS_ADMIN_OTHER
  $ADDRESS_COUNTRY
  $ADDRESS_POSTAL_CODE
  $ADDRESS_NEIGHBORHOOD
  $ADDRESS_ALL

These are the default components used by libpostal:

  use Geo::libpostal ':all';

  expand_address('120 E 96th St New York',
    components =&gt; $ADDRESS_NAME | $ADDRESS_HOUSE_NUMBER | $ADDRESS_STREET | $ADDRESS_UNIT
  );

The constant C&lt;$ADDRESS_ALL&gt; uses all components:

  expand_address('120 E 96th St New York',
    components =&gt; $ADDRESS_ALL
  );

C&lt;expand_address&gt; will C&lt;die&gt; on C&lt;undef&gt; 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&lt;die&gt; on C&lt;undef&gt; and empty addresses. Exported on request.

C&lt;parse_address&gt; may return L&lt;duplicate labels|https://github.com/openvenues/libpostal/issues/27&gt; for invalid addresses
strings.

=head1 WARNING

libpostal uses C&lt;setup&gt; and C&lt;teardown&gt; functions. Setup is lazily loaded. Teardown occurs in an C&lt;END&gt; block automatically.

=over 4

=item *

Old versions of libpostal C&lt;Geo::libpostal&gt; will L&lt;segfault|https://github.com/openvenues/libpostal/issues/82&gt; if C&lt;_teardown()&gt; is called twice (this module includes a unit test for this).

=item *

If C&lt;expand_address&gt; or C&lt;parse_address&gt; is called after teardown, old versions of libpostal will L&lt;error|https://github.com/openvenues/libpostal/pull/86&gt; (this module includes a unit test for this too).

=item *

libpostal is not L&lt;thread-safe|https://github.com/openvenues/libpostal/issues/34&gt;.

=back

=head1 EXTERNAL DEPENDENCIES

L&lt;libpostal|https://github.com/openvenues/libpostal&gt; is required. C&lt;Geo::libpostal&gt; uses pkg-config to support custom install locations. Sometimes pkg-config can't find the library by default, in those cases just do:

  $ find / -name libpostal.pc 2&gt;/dev/null
  /usr/local/lib/pkgconfig/libpostal.pc

  $ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig

And then do a manual installation of C&lt;Geo::libpostal&gt;.

=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&lt;copy&gt; 2016 David Farrell

=head1 LICENSE

See LICENSE


=cut

</pre></body></html>