User:SignpostMarv Martin/Webmap API

What is it?

The MN:SL Webmap API is a rewrite of the official Webmap API, focusing on the data and on improved server-side queries.

Disclaimer Keep in mind that any changes to the URL structure of the Linden Lab API may result in the MN:SL cache falling out of sync with the actual data, so map images may not be displayed, or turn up in the wrong place.

Getting Started

There is no need to sign up for anything to use the server API.

As the MN:SL Webmap API focuses on the data, the client script lacks any fancy effects, so you may wish to write your own client interface to the server API.

The latest reference implementation will be available at http://static.marvulous.co.uk/js/map-api.js

Server API Calls

The Server API currently supports two output formats:

1. JSON
2. JSONP

The JSON output format is aimed at server-side applications, the JSONP output is nearly identical to the JSON output with the exception that it attempts to auto-initialize a Javascript variable containing the results of the query.

Structure

http://svc.sl.net.marvulous.co.uk/output format/mapapi/query/parameters/

Getting the regions in range of another region

Query Structure:' region name/number of neighboring regions to fetch

Query Example: http://svc.sl.net.marvulous.co.uk/jsonp/mapapi/regions-in-range/Ahern/3/

The maximum number of results expected to be returned by the query will be (2n + 1) ^ 2, which in the example given would be a maximum of 49. The actual number of results returned may be lower, as the API doesn't return results for regions that do not exist. This is intentional, as it means that a client interface to the API should be loading fewer images into memory, especially when viewing private islands where the density of regions is relatively low

Getting the Parcels in the specified regions

Query Structure:' ?region[0]=first region name&region[1]=second region name&region[x]=subsequent region name

Query Example: http://svc.sl.net.marvulous.co.uk/jsonp/mapapi/parcels-in-regions/?regions[0]=Ahern&regions[1]=Waterhead

Gets all the parcels for the given regions. The UUID, name, region UUID & local co-ordinates are returned as part of the result set. See parcels_by_regions() in the reference implementation.

SLOpenID Map API Calls

The following calls are supported for "historical" reasons, as they were supported by my <a href="http://blog.slopenid.net/2007/04/12/slopenid-sl-maps-api/">old SL Map API</a>

region2coord

Used to find out the global co-ordinates of a region- similar effect to llGetRegionCorner(). Takes one argument, the name of a region.

Query Structure: region name/

Query Example: http://svc.sl.net.marvulous.co.uk/jsonp/mapapi/region2coord</style>/Ahern/

region2offset

Used to find out the relative position of a region within the grid. Takes one argument, the name of a region.

Query Structure: region name/

Query Example: http://svc.sl.net.marvulous.co.uk/jsonp/mapapi/region2offset</style>/Ahern/

region2ll

Similar to region2offset, but with the y-axis fitting Linden Lab's quirky webmap image y-axis format.

Query Structure: region name/

Query Example: http://svc.sl.net.marvulous.co.uk/jsonp/mapapi/region2ll</style>/Ahern/

offset2region

Used to find out the name of a region at a the specified grid offset. Takes two arguments, the horizontal and vertical offset.

Query Structure: x-axis offset/y-axis offset/

Query Example: http://svc.sl.net.marvulous.co.uk/jsonp/mapapi/offset2region</style>/997/1002

coord2region

Used to find out the name of a region at a the specified global co-ordinates. Takes two arguments, the x and y co-ordinates.

Query Structure: x-axis co-ordinate/y-axis co-ordinate/

Query Example: http://svc.sl.net.marvulous.co.uk/jsonp/mapapi/coord2region</style>/255232/256512

regionexists

Used for finding if a region exists or not. Takes one argument, the name of a region.

Query Structure: region name/

Query Example: http://svc.sl.net.marvulous.co.uk/jsonp/mapapi/regionexists</style>/Ahern/

Reference Implementation

range_by_region(region, range)

Uses json_p() to get the regions in range of the specified region.

parcels_by_regions(regions)

Uses json_p() to get the parcels for the specified regions..

The parameter should be provided as a one-dimensional array of region names.

json_p(url, id, handler)

Loads the JSONP request for the query. Similar to slAddDynamicScript in the Linden Lab wrapper[1] with the exception of the id parameter.

Appends a new script tag with the SRC and ID attributes set to url and id respectively.

Adding an ID to the script tag allows the script tag to be removed after parsing of the result, to avoid cluttering the DOM with useless data.

parse_results()

Copies the results of a query into a global variable, creates array of region UUIDs indexed by region name (avoiding scanning the global results variable for each name-based search), and executes addImage() for each new result.

Executes parcels_by_regions() for all regions not already fetched.

addImage(uuid,id)

Adds an image of the region with the given UUID to the document element specified by the id parameter.

Uses global2mapimage() to adjust the global region co-ordinate to the quirky Linden Lab y-axis scheme for webmap images.

Uses global2mapapi() to set the position of the image within the map element.

addParcels(data)

Adds a list element structured as an hCard for each parcel provided by parcels_by_regions().

imageCatch()

Used to detect when a region image has been clicked on, enabling the map to recenter as well as downloading surrounding images.

integer global2mapimage(y_coord)

Performs (1279 - (y_cord / 256)) and returns the result.

integer global2mapapi(y_coord)

Performs (1279 - (y_cord / 256)) * 256 and returns the result.

focus_at(x,y,id)

Attempts to focus the element specified by id on the specified global co-ordinates.

Uses global2mapapi() to account for the differences in the CSS and Second Life y-axis running in opposite directions.

focus_on(region,id)

Acts as a wrapper to focus_at(), allowing the focus to be set by region name.

change()

Keeps a track of the location fragment, as an example implementation of jumping from region to region without reloading the page while preserving the browser history.

Executes range_by_region() if the location has changed.

Try the following in sequence (you may need to paste the URLs into the same window depending on your browser configuration):

1. http://dev.signpostmarv.name/pub/secondlife/map-api.html#Ahern
2. http://dev.signpostmarv.name/pub/secondlife/map-api.html#Waterhead
3. http://dev.signpostmarv.name/pub/secondlife/map-api.html#Lanercost
4. http://dev.signpostmarv.name/pub/secondlife/map-api.html#Hippotropolis