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

NAME

Net::API::Nominatim::Model::BoundingBox - Storage class for the bounding box as returned by the Nominatim Service

VERSION

Version 0.03

DESCRIPTION

Net::API::Nominatim::Model::BoundingBox is an OO module which provides a class to store a generic 2-dimensional bounding box comprising of two latitude/longitude coordinates denoting its two opposite vertices, with assorted constructor, getters, setters and stringifiers.

It can be constructed empty whereas all coordinates are set to 0.0, or loaded with data passed in during construction.

SYNOPSIS

Example usage:

    use Net::API::Nominatim::Model::BoundingBox;

    # construct from a hash of parameters,
    # the keys must be exactly these:
    my $bbox = Net::API::Nominatim::Model::BoundingBox->new({
        lat1 => 30.12, lon1 => 12.22, lat2 => 30.15, lon2 => 12.5
    });

    # construct from a JSON string like the one used and returned
    # by Nominatim.
    my $bbox = Net::API::Nominatim::Model::BoundingBox->new(
        #  lat1, lat2,  lon1,  lon2
	"[30.12, 30.15, 12.22, 12.5]"
    );

    # construct from an ARRAY whose order is the same
    # as the one used and returned by Nominatim.
    my $bbox = Net::API::Nominatim::Model::BoundingBox->new(
        #  lat1, lat2,  lon1,  lon2
	[30.12, 30.15, 12.22, 12.5]
    );

    # construct from an ARRAY of ARRAYs of [lat,lon]
    my $bbox = Net::API::Nominatim::Model::BoundingBox->new(
        #  lat1, lon2,    lat2,  lon2
	[[30.12, 12.22], [30.15, 12.5]]
    );

    # print as the last example
    print $bbox->toString();

    # print as JSON like the one used by Nominatim
    print $bbox->toJSON();

    # additionally there are (non-)exportable factory subs
    # construct from a hash of parameters,
    # the keys must be exactly these:
    my $bbox = Net::API::Nominatim::Model::BoundingBox::fromHash({
        lat1 => 30.12, lon1 => 12.22, lat2 => 30.15, lon2 => 12.5
    });

    # construct from a JSON string like the one used and returned
    # by Nominatim.
    my $bbox = Net::API::Nominatim::Model::BoundingBox::fromJSONArray(
        #  lat1, lat2,  lon1,  lon2
	"[30.12, 30.15, 12.22, 12.5]"
    );

    # construct from an ARRAY whose order is the same
    # as the one used and returned by Nominatim.
    my $bbox = Net::API::Nominatim::Model::BoundingBox::fromArray(
        #  lat1, lat2,  lon1,  lon2
	[30.12, 30.15, 12.22, 12.5]
    );

    # construct from an ARRAY of ARRAYs of [lat,lon]
    my $bbox = Net::API::Nominatim::Model::BoundingBox::fromArrayOfArrays(
        #  lat1, lon2,    lat2,  lon2
	[[30.12, 12.22], [30.15, 12.5]]
    );

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::BoundingBox::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:

  • an ARRAY_REF of [lat1, lat2, lon1, lon2]. The specific order is what the actual Nominatim service returns.

  • an ARRAY_REF of arrays of [lat,lon], e.g. [ [lat1,lon1], [lat2,lon2] ].

  • a HASH_REF which must contain one to four items keyed on lat1, lat2, lon1, lon2. Values for whatever missing keys will be set to 0.0.

  • a JSON string of "[lat1, lat2, lon1, lon2]". The specific order is what the actual Nominatim service returns.

RETURN

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

lat1

Setter and Getter for the latitude lat1 of the first vertex of the bounding box.

lat2

Setter and Getter for the longitude lon1 of the first vertex of the bounding box.

lon1

Setter and Getter for the latitude lat2 of the second vertex of the bounding box.

lon2

Setter and Getter for the longitude lon2 of the second vertex of the bounding box.

toString

It returns the bounding box as this string "[ [lat1,lon1], [lat2,lon2] ]".

toJSON

It returns the bounding box as this JSON string "[ lat1, lat2, lon1, lon2 ]".

clone

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

equals

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.

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-BoundingBox. 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::BoundingBox

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)