Geo::OSM library
.svg){kind=icon}
If you have fixed the software, or concluded that this notice does not apply, remove it.
. The information is no longer correct, or no longer has relevance.If you know about the current state of affairs, please help keep everyone informed by updating this information.
(Discussion)The Geo::OSM library is a set of perl modules to make it quick and easy to write programs that manipulate OSM data, either from disk files or directly from the API. The library exists in both v0.3 and v0.5 versions with a similar API so programs using one version can be easily upgraded.
This library uses proper XML reading and writing, no regexes. It supports multiple keys in tags.
There are 4 main components:
- Geo::OSM::Entities - Defines the objects used by the rest of the library
- Geo::OSM::APIClient - Provides a library to upload and download data from an OSM API server
- Geo::OSM::OsmReader - For reading (as a stream) objects from an on disk file or in memory string
- Geo::OSM::OsmChangeRender - For reading (as a stream) change from JOSM files or osmChange files
Each of these comes in two versions, v3/v4 and v5. As of this writing the main server is v3/v4 but the v5 version can be used on the experimental servers.
As a demonstration, here is the simplest program using the Geo::OSM library:
use Geo::OSM::APIClientV3;
my $client = init Geo::OSM::APIClient( api => 'http://www.openstreetmap.org/api/0.4' );
print $client->get_way(4831343)->xml;
This gets the specified way and prints it to the output as XML. However, much more is possible.
Geo::OSM::Entities
This module provides an object-oriented view of the object types in OSM. It consists of several classes:
- Geo::OSM::Entity - Parent class providing common methods
- Geo::OSM::Node - A node
- Geo::OSM::Segment - (v3/v4 only) A segment
- Geo::OSM::Relation - (v5 only) A relation
- Geo::OSM::Relation::Member - (v5 only) A member of a relation (the reference)
- Geo::OSM::Way - A way
A quick overview of the public methods follows:
Geo::OSM::Entity
- add_tag(key,value)
- add_tags( key, value, key, value, ... )
- set_tags( @tags )
- set_tags( %tags )
- tags (return @tags)
- id
- timestamp
- set_id(id)
- set_timestamp(string)
- type (returns "node", "segment", "way" or "relation")
- xml (return XML description of object)
- map(mapper)
Geo::OSM::Way
In v3/v4:
- new ({id => $id, timestamp => $timestamp}, \@tags, \@segs )
- segs (returns @segs)
- set_segs(@segs)
In v5:
- new ({id => $id, timestamp => $timestamp}, \@tags, \@nodes )
- nodes (returns @nodes)
- set_nodes(@nodes)
Geo::OSM::Segment
(v3/v4 only)
- new ({id => $id, timestamp => $timestamp, from=>$from, to=>$to}, \@tags)
- set_fromto(from,to)
- from (returnd id)
- to (returns id)
Geo::OSM::Relation
(v5 only)
- new ({id => $id, timestamp => $timestamp}, \@tags, \@members )
- A member can be described as one of:
- { type => $type, ref => $id , role => $str }
- { ref => $obj , role => $str ] }
- [ $type, $id ,$role ]
- [ $obj ,$role ]
- Geo::OSM::Relation::Member object
- set_member( \@members )
- Each member can be described as above.
Geo::OSM::Relation::Member
(v5 only) Note this is not derived from Geo::OSM::Entity, but does share some of its methods:
- new(args)
- args can be one of:
- { type => $type, ref => $id , role => $str }
- { ref => $obj , role => $str ] }
- [ $type, $id ,$role ]
- [ $obj, ,$role ]
- member_type
- role
- ref
- type (returns "relation:member")
- map(mapper)
Geo::OSM::Node
- new ({id => $id, timestamp => $timestamp, lat=>$lat, lon=>$lon}, \@tags)
- lat
- lon
- set_latlon(lat,lon)
Geo::OSM::APIClient
This module provides an interface to an API server via HTTP. The correspond directly to the defined API calls. This module comes in two forms depending ont he version of the api you would like to use:
Note: not all the calls on the API are currently implemented. They should be trivial to add if you need them.
Methods are:
- new( api =>url, username => username, password => password )
- Creates a new client. The username and password are optional if you only intend to download stuff.
- last_error_code
- last_error_message
- Normally when one of the function fails it returns undef. In that case these functions can be used to find out the problem.
- create(ent)
- modify(ent)
- delete(ent)
- These take instantiated Geo::OSM::Entites objects and do the appropriate action on the server. For the creation the ID of the entity is ignored. In all cases the ID of the entity (new if created) is returned or undef on failure.
- get(type,id)
- get_node(id)
- get_segment(id) (v3/4 only)
- get_relation(id) (v5 only)
- get_way(id)
- Get an object from the server. type can be one of "node", "segment", "relation", "way". The object is returned or undef on failure.
- bbox(bllon,bllat,trlon,trlat)
- (bl=bottom left, tr=top right). Returns a an array reference of the objects returned by the server.
Geo::OSM::OsmReader
For parsing files or strings of OSM data and calling a callback whenever an object is parsed. comes in two forms:
Methods are:
- init( \&process, \&progress )
- Creates a new object with the given functions. The process function is required and will be called as:
process->(ent)
- Where ent is an instantiated Geo::OSM object. The progress function is optional and is called as:
progress->(count,percentage)
- The count is the number of objects processed so far, the percentage is an estimate of the percentage based on the progress through the file.
- load(filename)
- parse(string)
- Starts the parsing process on either a file or a string, as appropriate. The process function will be called for each object and when the end of file is reached, it will return.
Geo::OSM::OsmChangeReader
Exactly the same interface as the Geo::OSM::OsmReader module, except that the process function is called with:
process->(command, ent)
Where command is one of "create", "modify" or "delete".