Difference between revisions of "User:SignpostMarv Martin/Webmap API"
(added imageCatch() function docs) |
(updated manual) |
||
| Line 32: | Line 32: | ||
The maximum number of results expected to be returned by the query will be <code style="font-size:1.5em;">(2n + 1) ^ 2</code>, 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. <em>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</em> | The maximum number of results expected to be returned by the query will be <code style="font-size:1.5em;">(2n + 1) ^ 2</code>, 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. <em>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</em> | ||
=== Getting the Parcels in the specified regions === | |||
'''Query Structure:'''' | |||
<code style="font-size:2em;">?region[0]=<strong style="color:red;">first region name</strong><em>®ion[1]=<strong style="color:red;">second region name</strong></em><em>®ion[x]=<strong style="color:red;">subsequent region name</strong></em></code> | |||
'''Query Example:''' | |||
<code style="font-size:1.5em;"><nowiki>http://svc.sl.net.marvulous.co.uk/jsonp/mapapi/parcels-in-regions/?</nowiki><strong style="color:red;">regions[0]=Ahern</strong>&<strong style="color:red;">regions[1]=Waterhead</strong></code> | |||
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|parcels_by_regions()]] in the reference implementation. | |||
== Reference Implementation == | == Reference Implementation == | ||
| Line 39: | Line 50: | ||
</div> | </div> | ||
</div> | </div> | ||
<div id="box"> | |||
<h2 id="parcels_by_regions">parcels_by_regions(<em>regions</em>)</h2> | |||
<div style="padding:0.5em;">Uses [[#json_p|json_p()]] to [[#Getting the Parcels in the specified regions|get the parcels for the specified regions.]]. | |||
The parameter should be provided as a one-dimensional array of region names. | |||
</div> | |||
</div> | |||
<div id="box"> | <div id="box"> | ||
<h2 id="json_p">json_p(<em>url</em>, <em>id</em>, <em>handler</em>)</h2> | <h2 id="json_p">json_p(<em>url</em>, <em>id</em>, <em>handler</em>)</h2> | ||
| Line 53: | Line 74: | ||
<div style="padding:0.5em;"> | <div style="padding:0.5em;"> | ||
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|addImage()]] for each new result. | 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|addImage()]] for each new result. | ||
Executes [[#parcels_by_regions|parcels_by_regions()]] for all regions not already fetched. | |||
</div> | </div> | ||
</div> | </div> | ||
| Line 63: | Line 86: | ||
Uses [[#global2mapapi|global2mapapi()]] to set the position of the image within the map element. | Uses [[#global2mapapi|global2mapapi()]] to set the position of the image within the map element. | ||
</div> | |||
</div> | |||
<div id="box"> | |||
<h2 id="addParcels">addParcels(<em>data</em>)</h2> | |||
<div style="padding:0.5em;">Adds a list element structured as an hCard for each parcel provided by [[#parcels_by_regions|parcels_by_regions()]]. | |||
</div> | </div> | ||
</div> | </div> | ||
Revision as of 04:59, 30 December 2007
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
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://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®ion[1]=second region name®ion[x]=subsequent region name
Query Example:
http://svc.sl.net.marvulous.co.uk/jsonp/mapapi/parcels-in-regions/?regions[0]=Ahern®ions[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.
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):