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

Reference Implementation

range_by_region(region, range)

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

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.

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.

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