NAME
Database::BI::Model::Boundary - The outline of the area around each map marker
VERSION
0.023.1
SYNOPSIS
use Database::BI::Model::Boundary;
my $boundary = Database::BI::Model::Boundary->new(
cache => Database::BI::Model::Boundary->file_cache('.bi'),
online => 1,
level => 'state', # country, state, county (default), city, town, neighbourhood
);
my $result = $boundary->outlines([ [ 39.09, -77.64 ], [ 38.85, -77.31 ] ]);
$map->add_geojson(
{ type => 'FeatureCollection', features => $result->{features} },
name => 'County boundaries',
);
# A point the map page listed as pending, looked up on its own
my $answer = $boundary->lookup_point($result->{pending}[0]);
DESCRIPTION
Finds the area each point is in, at one level, and returns its outline as a GeoJSON Feature, for HTML::OSM's add_geojson. The outlines come from OpenStreetMap's Nominatim reverse lookup, through the same throttled user agent as the geocoder ("nominatim_ua" in Database::BI::Model::Geocode), so the two together never ask more than once a second.
Only the point is sent, rounded to three decimal places (about 110 metres). Every answer is cached: a point with the outline it is in, and the outline itself. A point inside an outline already known is matched here, without a request, so many points in one county cost one lookup.
The levels, largest first:
- country
- state
-
A US or Indian state, a Canadian province, a New Zealand region, England.
- county
-
The default; see below.
- city
-
A city or the district named after it: Toronto, Manchester, the district of Canterbury, Hamilton City in New Zealand. Where OpenStreetMap has no city round a point, or has the city only as a point (York, Pune), the area at the county's rank there: the unitary authority, the city district, or the county itself.
- town
-
A town or city ward: Margate, Toronto Centre. An English town that is a civil parish (Westgate-on-Sea) is that parish.
- neighbourhood
-
A neighbourhood, suburb or civil parish that OpenStreetMap has as an area. Many suburbs are mapped only as a point, and those have no outline.
Larger areas are simplified more, so an outline is a few kilobytes at any level.
A county here is the division of a country below its states, whose place rank in Nominatim depends on the country: 12 (a US county or independent city, an English county, a German Landkreis, a French departement) unless the country is listed otherwise: 10 for India, Bangladesh, China and Spain (district, prefecture, province), 8 for Kenya. ranks adds or changes countries. Anything else Nominatim answers is taken as "no county here" and remembered as such. A country with nothing at its rank (Australia, Brazil, Japan) gets no outlines.
Each reply names the point's country, so a point is asked at the zoom of the last country seen, and asked again when its own country wants another rank. An outline is kept with the rank it was accepted at; when ranks changes, the points it covered are asked again.
METHODS
new
my $boundary = Database::BI::Model::Boundary->new(%args);
API SPECIFICATION
INPUT
cache : object with get() and set() (CHI) optional; default one
CHI Memory cache for the process
online : boolean optional, default 0: may Nominatim be asked
online_max : integer optional, default 20: requests in one outlines() call
level : string optional, default 'county'; one of levels()
ranks : hashref optional: { country code => place rank }, over the
county level's own list; codes are two letters (any case),
ranks 8, 10 or 12. The other levels ignore it
ua : object with get() optional: the user agent to ask with
(tests); default Geocode::nominatim_ua()
OUTPUT
A Database::BI::Model::Boundary object. Croaks on an unknown level, a cache without get and set, or ranks that are not a hash of two-letter codes to 8, 10 or 12.
check_ranks
my $ranks = Database::BI::Model::Boundary->check_ranks({ LK => 10 }); # { lk => 10 }
API SPECIFICATION
INPUT
ranks : hashref of { country code => place rank }
OUTPUT
A new hashref with the codes in lower case and the ranks as numbers. Croaks on a value that is not a hashref, a key that is not a two-letter code, or a rank that is not 8, 10 or 12, naming the entry. Used by new and by the application's startup check of map_bounds_ranks.
rank_for
my $rank = $boundary->rank_for('in'); # 10
API SPECIFICATION
INPUT
country : string, an ISO 3166-1 alpha-2 code in any case; undef or ''
for a point in no country (the sea)
OUTPUT
The place rank an outline in that country must have at the county level: the country's own, from ranks or the built-in list, else 12. At another level, the most detailed rank its first try takes there.
name_for
my $word = $boundary->name_for('in'); # 'district'
What this object's level is called in a country, so a caller can say "district" on a map of India rather than "county".
API SPECIFICATION
INPUT
country : string, an ISO 3166-1 alpha-2 code in any case; undef or ''
for a point in no country
OUTPUT
One lower-case English word: country, state, region, province, prefecture, county, district, department, city, town or neighbourhood. A country not listed gets the level's own name ("level_name"). It is a word to look a translation up by, not text to show. Called on the class, it answers for the county level.
level_name
my $word = Database::BI::Model::Boundary->level_name('state'); # 'state'
API SPECIFICATION
INPUT
level : string, one of levels()
OUTPUT
What the level's areas are called where no country says otherwise, as "name_for" gives it: the word to use before a point's country is known. Undef for a level that is not one.
levels
my @levels = Database::BI::Model::Boundary->levels;
# ('country', 'state', 'county', 'city', 'town', 'neighbourhood')
API SPECIFICATION
INPUT
None.
OUTPUT
The names of the levels new() takes, the largest area first.
point_key
my $key = Database::BI::Model::Boundary->point_key(39.0901, -77.6402); # '39.090,-77.640'
API SPECIFICATION
INPUT
lat : number -90 .. 90
lon : number -180 .. 180
OUTPUT
The point rounded to three decimal places, as "lat,lon": what the cache is keyed by and all of the point that is sent. Undef for a point out of range.
outlines
my $result = $boundary->outlines(\@points, lookup => 1);
API SPECIFICATION
INPUT
points : arrayref of [lat, lon]
lookup : boolean, default 1. 0 asks Nominatim nothing: the points not
known yet come back in pending, for the caller to look up one at
a time (lookup_point)
OUTPUT
{
features => [ GeoJSON Feature, ... ] one per outline, in the order
their first point came; properties { name, osm, called }
(called: what the division is called there, as name_for)
pending => [ point_key, ... ] points not known, not asked
inside => { point_key => osm, ... } the outline each point drawn is in,
by the osm of its Feature (to total what is in each)
counts => { points, drawn, attempted, nowhere }
offline => 0|1 points were left because Nominatim may not be asked
failed => 0|1 Nominatim did not answer; the rest were left
}
A point out of range is ignored. A Feature's name is the place's name as OpenStreetMap has it: text, not HTML.
lookup_point
my $answer = $boundary->lookup_point('39.090,-77.640');
API SPECIFICATION
INPUT
key : string, a point_key
OUTPUT
{ status => 'found' | 'nowhere' | 'held', name => string|undef, asked => 0|1 }
'found' and 'nowhere' are remembered. 'held' is a point that could not be settled now - Nominatim did not answer, or may not be asked - and is asked again next time. asked says whether Nominatim was asked. Croaks on a key that is not a point_key.
file_cache
my $cache = Database::BI::Model::Boundary->file_cache($model_dir);
API SPECIFICATION
INPUT
dir : string, an existing directory (model_dir)
OUTPUT
A CHI File cache under <dir>/boundary-cache, with a copy of what it reads in memory for as long as the cache object lives. Croaks when dir is not a directory.
AUTHOR
Nigel Horne <njh@nigelhorne.com>
LICENCE AND COPYRIGHT
Copyright 2026 Nigel Horne.
Usage is subject to the GPL2 licence terms. If you use it, please let me know.