Potlatch 1/Remote calls

Summary

This page documents Potlatch's inner workings before API 0.5 went live. Most of the information is still essentially current, but some extra methods and parameters have been added - see amf_controller.rb for more. The page will be updated in due course.

The following methods are supported by amf_controller.rb:

• getway: get a way as an ordered list of nodes, with supplementary information
• putway: save a way in the database
• deleteway: delete a way from the database
• whichways: return list of all ways in a bounding box
• getpresets: return array of key/value preset menus

Common features

Queries that write to the database (i.e. putway/deleteway) require authentication via a valid OSM website user token.

All queries take care not to delete any segments and nodes that are used in other ways.

getway

Get a way as an ordered list of nodes.

Called with

• objectname (string describing ActionScript source object name)
• way ID
• base longitude of map
• base y co-ordinate of map
• masterscale of map (typically 5825.4222222222 with Yahoo base layer)

Returns

Array comprising:

• objectname (unchanged string)
• array of points
• way keys/values (hash)
• xmin (minimum x co-ordinate of way)
• xmax (maximum y co-ordinate of way)
• ymin (minimum y co-ordinate of way)
• ymax (maximum y co-ordinate of way)

Notes

For the reason why objectname is passed through, see here. However, as objectname is always equivalent to the way ID, it could probably be removed in this case.

putway

Save a way in the database.

Called with

• usertoken (string)
• way ID (<0 for new way)
• array of points
• way keys/values (hash)
• base longitude of map
• base y co-ordinate of map
• masterscale of map (typically 5825.4222222222 with Yahoo base layer)

Returns

• previous way ID (unchanged)
• new way ID (i.e. if written to the database for the first time)
• hash of any renumbered nodes (old node ID as key, new node ID as value)
• hash of any newly numbered segments (position in array as key, new segment ID as value)
• xmin (minimum x co-ordinate of way)
• xmax (maximum y co-ordinate of way)
• ymin (minimum y co-ordinate of way)
• ymax (maximum y co-ordinate of way)

Notes

See /putway SQL.

deleteway

Delete a way from the database, including all constituent segments/nodes.

Called with

• usertoken (string)
• way ID

Returns

• way ID

whichways

Return list of all ways in a bounding box.

Called with

Bounding box in this order:

• left
• bottom
• right
• top

Returns

List of way IDs.

Notes

At present, whichways does not use the correct SQL to find ways whose start and end points are both outside the box, but which nonetheless cross through. Instead, it requests a slightly larger bounding box.

getpresets

Read key/value preset menus from file.

Called with

Nothing.

Returns

Array comprising:

• presets (hash)
• presetmenus (hash)
• presetnames (hash)