/ 
Net-API-Nominatim-0.03
/ Net::API::Nominatim::Model::Address

NAME

Net::API::Nominatim::Model::Address - Storage class for the address data as returned by the Nominatim Service

VERSION

Version 0.03

DESCRIPTION

Net::API::Nominatim::Model::Address provides a Class for storing the address data as returned by Nominatim search, with assorted constructor, getters, setters and stringifiers.

It can be constructed empty whereas all fields will be set to empty string and the bounding box set to undef or loaded with, possibly incomplete, data passed in during construction. Any missing data will be set to empty strings except for the bounding box which will be set to undef.

SYNOPSIS

Example usage:

    use Net::API::Nominatim::Model::Address;

    my $address = Net::API::Nominatim::Model::Address->new({
	'lat' => ...
	'lon' => ...
	'name' => ...
	...
    });

    # or use the Random factory
    my $address = Net::API::Nominatim::Model::Address::fromRandom();

    # or use the JSON factory
    # this returns just a single address from a JSON hash
    # Nominatim's /reverse (for reverse geocoding) returns such JSON hash
    my $address = Net::API::Nominatim::Model::Address::fromJSONHash($jsonstr);

    # this returns an array of Address objects,
    # Nominatim's /search returns such JSON array-of-hashes
    my $addresses = Net::API::Nominatim::Model::Address::fromJSONArray($jsonstr);

    # stringify
    print $address->toString();

    # print as JSON string like the one returned by Nominatim's /search
    print $address->toJSON();

    # additionally there are (non-)exportable factory subs
    # construct from a hash of parameters,
    # the keys must be exactly these:
    my $address = Net::API::Nominatim::Model::Address::fromHash({
        ...
    });

EXPORT

Nothing is exported because the sane choice for sub names makes them too common thus a clash is imminent or they must be of huge lengths in order to ensure uniqueness. TLDR, use the fully qualified sub name, like Net::API::Nominatim::Model::Address::fromRandom().

METHODS

new

The constructor can take zero or one parameters. If zero, then the returned object contains 0.0 for all coordinates.

The optional parameter can be:

  • a HASH_REF which must contain any of these fields which are stored under this name internally. Note that there are setters and getters for each of these fields.

    • place_id

    • osm_type

    • osm_id

    • lat

    • lon

    • name

    • type

    • place_rank

    • boundingbox

    • category

    • addresstype

    • importance

    • display_name

    • licence

    All missing values will be set to a blank string. Except for boundingbox which will be left undef.

  • a JSON string containing just one hash which represents just one Address with one or more fields as outlined above. This JSON string is usually returned by Nominatim's /reverse. Nominatim's /search returns a JSON string of an array of hashes and you can not use that here, obviously (hint: use factory method fromJSONArray).

  • an Net::API::Nominatim::Model::Address object which we will clone it into the returned new Address object.

RETURN

The constructor will return undef on failure which can happen only if the input JSON string specified does not validate as JSON. It will not die.

toString

print $address->toString();

It returns a stringified version of this object.

toJSON

my $jsonstr = $address->toJSON();

It returns a JSON string containing a hash with all the fields of this object.

clone

my $newaddress = $address->clone();

It returns a totally new Net::API::Nominatim::Model::Address object deep-cloned from current object.

equals

my $yes = $address->equals($anotheraddress);

It compares current object to the input object and returns 1 if they are equal or 0 if they are not. Missing values (which are blank strings or undef objects) will also count in the comparison.

randomise

$address->randomise();

It overwrites all fields with random strings, including those which were blank. boundingbox will also be randomised as per Net::API::Nominatim::Model::BoundingBox::randomise.

fromHash

my $address = Net::API::Nominatim::Model::Address::fromHash({...});

Factory method to create a new Net::API::Nominatim::Model::Address object given an input HASH_REF with one or more fields this object contains, mentioned in the constructor.

fromArray

my $addressesARRAY = Net::API::Nominatim::Model::Address::fromArray([{...},{...},...]);

Factory method to create an ARRAY_REF of Net::API::Nominatim::Model::Address objects given an input ARRAY_REF in which each item is a HASH_REF containing the data for a single address. Its fields are mentioned in the constructor.

fields

It returns all the fields stored in an Net::API::Nominatim::Model::Address object as an array.

place_id

If a parameter is provided then it sets the value of field place_id to it, otherwise it returns the value of field place_id.

osm_type

If a parameter is provided then it sets the value of field osm_type to it, otherwise it returns the value of field osm_type.

osm_id

If a parameter is provided then it sets the value of field osm_id to it, otherwise it returns the value of field osm_id.

lat

If a parameter is provided then it sets the value of field lat to it, otherwise it returns the value of field lat.

lon

If a parameter is provided then it sets the value of field lon to it, otherwise it returns the value of field lon.

name

If a parameter is provided then it sets the value of field name to it, otherwise it returns the value of field name.

type

If a parameter is provided then it sets the value of field type to it, otherwise it returns the value of field type.

place_rank

If a parameter is provided then it sets the value of field place_rank to it, otherwise it returns the value of field place_rank.

boundingbox

If a parameter is provided then it sets the value of field boundingbox to it, otherwise it returns the value of field boundingbox.

category

If a parameter is provided then it sets the value of field category to it, otherwise it returns the value of field category.

addresstype

If a parameter is provided then it sets the value of field addresstype to it, otherwise it returns the value of field addresstype.

importance

If a parameter is provided then it sets the value of field importance to it, otherwise it returns the value of field importance.

display_name

If a parameter is provided then it sets the value of field display_name to it, otherwise it returns the value of field display_name.

licence

If a parameter is provided then it sets the value of field licence to it, otherwise it returns the value of field licence.

AUTHOR

Andreas Hadjiprocopis, <bliako at cpan.org>

BUGS

Please report any bugs or feature requests to bug-net-api-nominatim-model-boundingbox at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-API-Nominatim-Model-Address. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Net::API::Nominatim::Model::Address

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

This software is Copyright (c) 2025 by Andreas Hadjiprocopis.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)