|
|
| (5 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| __TOC__
| | {{hint|mode=important|desc=This map API has been retired along with the [http://blog.signpostmarv.name/2009/04/30/retiring-swslr-project/ swslr project]. However, Marv has made [[User:SignpostMarv Martin/Webmap API Examples|some improvements to the official SLURL javascript]].}} |
| <div id="box">
| |
| == 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.
| |
| </div>
| |
| | |
| == Getting Started ==
| |
| {{Alert Box|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:
| |
| # [http://www.json.org/ 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 ===
| |
| <code style="font-size:1.5em;"><nowiki>http://agni.sl.mapapi.net/</nowiki><strong style="color:red;">output format</strong><nowiki>/</nowiki><strong style="color:red;">query</strong>/<strong style="color:red;">parameters</strong>/</code>
| |
| | |
| === Getting the regions in range of another region ===
| |
| '''Query Structure:''''
| |
| <code style="font-size:2em;"><strong style="color:red;">region name</strong>/<strong style="color:red;">number of neighboring regions to fetch</strong></code>
| |
| | |
| '''Query Example:'''
| |
| <code style="font-size:1.5em;"><nowiki>http://agni.sl.mapapi.net/</nowiki><strong style="color:red;">jsonp</strong>/<strong style="color:red;">regions-in-range</strong>/<strong style="color:red;">Ahern</strong>/<strong style="color:red;">3</strong>/</code>
| |
| | |
| 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://agni.sl.mapapi.net/jsonp/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.
| |
| | |
| === SLOpenID Map API Calls ===
| |
| The following calls are supported for "historical" reasons, as they were supported by my [http://blog.slopenid.net/2007/04/12/slopenid-sl-maps-api/ 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:'''
| |
| <code style="font-size:2em;"><strong style="color:red;">region name</strong>/</code>
| |
| | |
| '''Query Example:'''
| |
| <code style="font-size:1.5em;"><nowiki>http://agni.sl.mapapi.net/jsonp/</nowiki><strong style="color:red;">region2coord</strong>/<strong style="color:red;">Ahern</strong>/</code>
| |
| | |
| ==== region2offset ====
| |
| Used to find out the relative position of a region within the grid. Takes one argument, the name of a region.
| |
| | |
| '''Query Structure:'''
| |
| <code style="font-size:2em;"><strong style="color:red;">region name</strong>/</code>
| |
| | |
| '''Query Example:'''
| |
| <code style="font-size:1.5em;"><nowiki>http://agni.sl.mapapi.net/jsonp/</nowiki><strong style="color:red;">region2offset</strong>/<strong style="color:red;">Ahern</strong>/</code>
| |
| | |
| ==== region2ll ====
| |
| Similar to [[#region2offset|region2offset]], but with the y-axis fitting Linden Lab's quirky webmap image y-axis format.
| |
| | |
| '''Query Structure:'''
| |
| <code style="font-size:2em;"><strong style="color:red;">region name</strong>/</code>
| |
| | |
| '''Query Example:'''
| |
| <code style="font-size:1.5em;"><nowiki>http://agni.sl.mapapi.net/jsonp/</nowiki><strong style="color:red;">region2ll</strong>/<strong style="color:red;">Ahern</strong>/</code>
| |
| | |
| ==== 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:'''
| |
| <code style="font-size:2em;"><strong style="color:red;">x-axis offset</strong>/<strong style="color:red;">y-axis offset</strong>/</code>
| |
| | |
| '''Query Example:'''
| |
| <code style="font-size:1.5em;"><nowiki>http://agni.sl.mapapi.net/jsonp/</nowiki><strong style="color:red;">offset2region</strong>/<strong style="color:red;">997</strong>/<strong style="color:red;">1002</strong></code>
| |
| | |
| | |
| ==== 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:'''
| |
| <code style="font-size:2em;"><strong style="color:red;">x-axis co-ordinate</strong>/<strong style="color:red;">y-axis co-ordinate</strong>/</code>
| |
| | |
| '''Query Example:'''
| |
| <code style="font-size:1.5em;"><nowiki>http://agni.sl.mapapi.net/jsonp/</nowiki><strong style="color:red;">coord2region</strong>/<strong style="color:red;">255232</strong>/<strong style="color:red;">256512</strong></code>
| |
| | |
| ==== regionexists ====
| |
| Used for finding if a region exists or not. Takes one argument, the name of a region.
| |
| | |
| '''Query Structure:'''
| |
| <code style="font-size:2em;"><strong style="color:red;">region name</strong>/</code>
| |
| | |
| '''Query Example:'''
| |
| <code style="font-size:1.5em;"><nowiki>http://agni.sl.mapapi.net/jsonp/</nowiki><strong style="color:red;">regionexists</strong>/<strong style="color:red;">Ahern</strong>/</code>
| |
| | |
| == Reference Implementation ==
| |
| <div id="box">
| |
| <h2 id="range_by_region>range_by_region(<em>region</em>, <em>range</em>)</h2>
| |
| <div style="padding:0.5em;">Uses [[#json_p|json_p()]] to [[#Getting the regions in range of another region|get the regions in range of the specified region.]]
| |
| </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">
| |
| <h2 id="json_p">json_p(<em>url</em>, <em>id</em>, <em>handler</em>)</h2>
| |
| <div style="padding:0.5em;">Loads the JSONP request for the query. Similar to '''slAddDynamicScript''' in the Linden Lab wrapper[http://s3.amazonaws.com/static-secondlife-com/_scripts/slmapapi.js] 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.
| |
| </div>
| |
| </div>
| |
| | |
| <div id="box">
| |
| <h2 id="parse_results">parse_results()</h2>
| |
| <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.
| |
| | |
| Executes [[#parcels_by_regions|parcels_by_regions()]] for all regions not already fetched.
| |
| </div>
| |
| </div>
| |
| | |
| <div id="box">
| |
| <h2 id="addImage">addImage(<em>uuid</em>,<em>id</em>)</h2>
| |
| <div style="padding:0.5em;">Adds an image of the region with the given [[UUID]] to the document element specified by the <em>id</em> parameter.
| |
| | |
| Uses [[#global2mapimage|global2mapimage()]] to adjust the global region co-ordinate to the quirky Linden Lab y-axis scheme for webmap images.
| |
| | |
| 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 id="box">
| |
| <h2 id="imageCatch">imageCatch()</h2>
| |
| <div style="padding:0.5em;">Used to detect when a region image has been clicked on, enabling the map to recenter as well as downloading surrounding images.
| |
| </div>
| |
| </div>
| |
| | |
| <div id="box">
| |
| <h2 id="global2mapimage">integer global2mapimage(y_coord)</h2>
| |
| <div style="padding:0.5em;">Performs <code style="font-size:1.5em;">(1279 - (y_cord / 256))</code> and returns the result.</div>
| |
| </div>
| |
| | |
| <div id="box">
| |
| <h2 id="global2mapapi">integer global2mapapi(y_coord)</h2>
| |
| <div style="padding:0.5em;">Performs <code style="font-size:1.5em;">(1279 - (y_cord / 256)) * 256</code> and returns the result.
| |
| </div>
| |
| </div>
| |
| | |
| <div id="box">
| |
| <h2 id="focus_at">focus_at(x,y,id)</h2>
| |
| <div style="padding:0.5em;">Attempts to focus the element specified by <em>id</em> on the specified global co-ordinates.
| |
| | |
| Uses [[#global2mapapi|global2mapapi()]] to account for the differences in the CSS and Second Life y-axis running in opposite directions.
| |
| </div>
| |
| </div>
| |
| | |
| <div id="box">
| |
| <h2 id="focus_on">focus_on(region,id)</h2>
| |
| <div style="padding:0.5em;">Acts as a wrapper to [[#focus_at|focus_at()]], allowing the focus to be set by region name.
| |
| </div>
| |
| </div>
| |
| | |
| <div id="box">
| |
| <h2 id="change">change()</h2>
| |
| <div style="padding:0.5em;">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|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):
| |
| # http://agni.sl.mapapi.net/map-api.html#Ahern
| |
| # http://agni.sl.mapapi.net/map-api.html#Waterhead
| |
| # http://agni.sl.mapapi.net/map-api.html#Lanercost
| |
| # http://agni.sl.mapapi.net/map-api.html#Hippotropolis
| |
| </div>
| |
| </div>
| |
| [[Category:API|Webmap API]]
| |
