Difference between revisions of "User:SignpostMarv Martin/Webmap API"
m (→Getting the Parcels in the specified regions: example and implementation did not match documentation) |
Rob Linden (talk | contribs) |
||
| Line 204: | Line 204: | ||
</div> | </div> | ||
</div> | </div> | ||
[[Category:Map API VAG]] | [[Category:Map API VAG]] | ||
[[Category:Web Service APIs]] | |||
Revision as of 18:11, 29 January 2009
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
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
TMS Support
Inspired by Thraxis' suggestion for LL to support the Tile Map Service Specification, I've started adding TMS support by putting up an URL translation scheme similar to the one described by Thraxis Epsilon (but using different code of course).
Requesting Tiles
http://agni.sl.mapapi.net/tms/1.0.0/map/6/1000/1000.jpg
points to Da Boom
Server API Calls
The Server API currently supports two output formats:
- JSON
- 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://agni.sl.mapapi.net/output format/query/parameters/
Getting the regions in range of another region
Query Structure:'
region name/number of neighboring regions to fetch
Query Example:
http://agni.sl.mapapi.net/jsonp/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®ion[1]=second region name®ion[x]=subsequent region name
Query Example:
http://agni.sl.mapapi.net/jsonp/parcels-in-regions/?region[0]=Ahern®ion[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 old SL Map API
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://agni.sl.mapapi.net/jsonp/region2coord/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://agni.sl.mapapi.net/jsonp/region2offset/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://agni.sl.mapapi.net/jsonp/region2ll/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://agni.sl.mapapi.net/jsonp/offset2region/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://agni.sl.mapapi.net/jsonp/coord2region/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://agni.sl.mapapi.net/jsonp/regionexists/Ahern/
Reference Implementation
range_by_region(region, range)
parcels_by_regions(regions)
The parameter should be provided as a one-dimensional array of region names.
json_p(url, id, handler)
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)
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)
imageCatch()
integer global2mapimage(y_coord)
(1279 - (y_cord / 256)) and returns the result.integer global2mapapi(y_coord)
(1279 - (y_cord / 256)) * 256 and returns the result.
focus_at(x,y,id)
Uses global2mapapi() to account for the differences in the CSS and Second Life y-axis running in opposite directions.
focus_on(region,id)
change()
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):