Hawkin
/
arangodb
mirror of https://gitee.com/bigwinds/arangodb
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
arangodb/Doxygen/doc/IndexGeoHttp.html

290 lines
12 KiB
HTML
Raw Blame History

<html><head><title>ArangoDB Manual</title> <style media="screen" type="text/css" style="display:none">body{background-color:white;font:13px Helvetica,arial,freesans,clean,sans-serif;line-height:1.4;color:#333;}#access{font-size:16px;margin-left:12px;display:block;margin-left:10px;margin-right:10px;background-color:#F3F1EE!important;}#access a{border-right:1px solid #DBDEDF;color:#A49F96;display:block;line-height:38px;padding:0 10px;text-decoration:none;}#navigation ul{text-transform:uppercase;list-style:none;margin:0;}#navigation li{float:left;position:relative;}#container{width:920px;margin:0 auto;}a{color:#4183C4;text-decoration:none;}.contents h2{font-size:24px;border-bottom:1px solid #CCC;color:black;}.contents h1{font-size:33px;border-bottom:1px solid #CCC;color:black;}.clearfix:after{content:".";display:block;clear:both;font-size:0;height:0;visibility:hidden;}/**/ *:first-child+html .clearfix{min-height:0;}/**/ * html .clearfix{height:1%;}</style></head><body><div id="container"><img src="images/logo_arangodb.png" width="397" height="67" alt="ArangoDB"><div id="access" role="navigation"><div id="navigation"><ul id="menu-ahome" class="menu"><li><a href="Home.html">Table of contents</a></li> <li><a href="http://www.arangodb.org">ArangoDB homepage</a></li></ul></div><div class="clearfix"></div></div><div>
<!-- Generated by Doxygen 1.7.5.1 -->
</div>
<div class="header">
<div class="headertitle">
<h1>Accessing Geo Indexes via Http </h1> </div>
</div>
<div class="contents">
<div class="textblock"><hr/>
<ul>
<li>
<a class="el" href="IndexGeoHttp.html">Accessing Geo Indexes via Http</a> <ul>
<li>
<a class="el" href="IndexGeoHttp.html#IndexGeoHttpEnsureGeo">POST /_api/index</a> </li>
<li>
<a class="el" href="IndexGeoHttp.html#IndexGeoHttpNear">POST /_api/simple/near</a> </li>
<li>
<a class="el" href="IndexGeoHttp.html#IndexGeoHttpWithin">POST /_api/simple/within</a> </li>
</ul>
</li>
</ul>
<hr/>
<a class="anchor" id="IndexGeoHttpEnsureGeo"></a> <hr/>
<em>GET /_api/index</em> (creates a geo-spatial index)<hr/>
<br/>
<code><b>POST /_api/index?collection=<em>collection-identifier</em></b></code></p>
<p>Creates a geo-spatial index in the collection <em>collection-identifier</em>, if it does not already exist. Expects an object containing the index details.</p>
<ul>
<li><code>type</code>: must be equal to <code>"geo"</code>.</li>
</ul>
<ul>
<li><code>fields</code>: A list with one or two attribute paths. <br/>
<br/>
If it is a list with one attribute path <em>location</em>, then a geo-spatial index on all documents is created using <em>location</em> as path to the coordinates. The value of the attribute must be a list with at least two double values. The list must contain the latitude (first value) and the longitude (second value). All documents, which do not have the attribute path or with value that are not suitable, are ignored.<br/>
<br/>
If it is a list with two attribute paths <em>latitude</em> and <em>longitude</em>, then a geo-spatial index on all documents is created using <em>latitude</em> and <em>longitude</em> as paths the latitude and the longitude. The value of the attribute <em>latitude</em> and of the attribute <em>longitude</em> must a double. All documents, which do not have the attribute paths or which values are not suitable, are ignored.</li>
</ul>
<ul>
<li><code>geoJson</code>: If a geo-spatial index on a <em>location</em> is constructed and <code>geoJson</code> is <code>true</code>, then the order within the list is longitude followed by latitude. This corresponds to the format described in <br/>
<br/>
<a href="http://geojson.org/geojson-spec.html#positions">http://geojson.org/geojson-spec.html#positions</a></li>
</ul>
<ul>
<li><code>constraint</code>: If <code>constraint</code> is <code>true</code>, then a geo-spatial constraint instead of an index is created.</li>
</ul>
<ul>
<li><code>ignoreNull</code>: If a geo-spatial constraint is created and <em>ignoreNull</em> is true, then documents with a null in <em>location</em> or at least one null in <em>latitude</em> or <em>longitude</em> are ignored.</li>
</ul>
<p>If the index does not already exists and could be created, then a <code>HTTP 201</code> is returned. If the index already exists, then a <code>HTTP 200</code> is returned.</p>
<p>If the <em>collection-identifier</em> is unknown, then a <code>HTTP 404</code> is returned. It is possible to specify a name instead of an identifier.</p>
<p><b>Examples</b><br/>
</p>
<p>Creating a geo index with a location attribute:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X POST --dump - http://localhost:8529/_api/index?collection=95560976
{ "type" : "geo", "fields" : [ "b" ] }
HTTP/1.1 201 Created
content-type: application/json
{
"code": 201,
"geoJson": false,
"fields": [
"b"
],
"id": "95560976/162222265",
"type": "geo1",
"constraint" : false,
"isNewlyCreated": true,
"error": false
}
</pre></div><p>Creating a geo index with latitude and longitude attributes:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X POST --dump - http://localhost:8529/_api/index?collection=99886352
{ "type" : "geo", "fields" : [ "e", "f" ] }
HTTP/1.1 201 Created
content-type: application/json
{
"code": 201,
"fields": [
"e",
"f"
],
"id": "99886352/165564601",
"type": "geo2",
"constraint" : false,
"isNewlyCreated": true,
"error": false
}
</pre></div> <p><a class="anchor" id="IndexGeoHttpNear"></a> <hr/>
<em>PUT /_api/simple/near</em> (executes simple query "near")<hr/>
<br/>
<code><b>PUT /_api/simple/near</b></code></p>
<p>The default will find at most 100 documents near a given coordinate. The returned list is sorted according to the distance, with the nearest document coming first. If there are near documents of equal distance, documents are chosen randomly from this set until the limit is reached.</p>
<p>In order to use the <code>near</code> operator, a geo index must be defined for the collection. This index also defines which attribute holds the coordinates for the document. If you have more then one geo-spatial index, you can use the <code>geo</code> field to select a particular index.</p>
<p>The call expects a JSON hash array as body with the following attributes:</p>
<ul>
<li><code>collection</code>: The identifier or name of the collection to query.</li>
</ul>
<ul>
<li><code>latitude</code>: The latitude of the coordinate.</li>
</ul>
<ul>
<li><code>longitude</code>: The longitude of the coordinate.</li>
</ul>
<ul>
<li><code>distance</code>: If given, the attribute key used to store the distance. (optional)</li>
</ul>
<ul>
<li><code>skip</code>: The number of documents to skip in the query. (optional)</li>
</ul>
<ul>
<li><code>limit</code>: The maximal amount of documents to return. The <code>skip</code> is applied before the <code>limit</code> restriction. The default is 100. (optional)</li>
</ul>
<ul>
<li><code>geo</code>: If given, the identifier of the geo-index to use. (optional)</li>
</ul>
<p>Returns a cursor containing the result, see <a class="el" href="HttpCursor.html">HTTP Interface for AQL Query Cursors</a> for details.</p>
<p><b>Examples</b><br/>
</p>
<p>Without distance:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/near
{ "collection" : "11172897562", "latitude" : 0, "longitude" : 0, "skip" : 1, "limit" : 2 }
HTTP/1.1 201 Created
content-type: application/json
{
"hasMore": false,
"count": 5,
"result": [
{
"_id": "11172897562/11178271514",
"loc": [ 0, -10 ],
"_rev": 11178271514
},
{
"_id": "11172897562/11177616154",
"loc": [ -10, 0 ],
"_rev": 11177616154
}
],
"code": 201,
"error": false
}
</pre></div><p>With distance:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/near
{ "collection" : "11182465818", "latitude" : 0, "longitude" : 0, "limit" : 2, "distance" : "distance" }
HTTP/1.1 201 Created
content-type: application/json
{
"hasMore": false,
"count": 5,
"result": [
{
"distance": 0,
"_id": "11182465818/11187905306",
"loc": [ 0, 0 ],
"_rev": 11187905306
},
{
"distance": 1111949.26644559,
"_id": "11182465818/11187839770",
"loc": [ 0, -10 ],
"_rev": 11187839770
}
],
"code": 201,
"error": false
}
</pre></div> <p><a class="anchor" id="IndexGeoHttpWithin"></a> <hr/>
<em>PUT /_api/simple/within</em> (executes simple query "within")<hr/>
<br/>
<code><b>PUT /_api/simple/within</b></code></p>
<p>This will find all documents with in a given radius around the coordinate (<em>latitude</em>, <em>longitude</em>). The returned list is sorted by distance.</p>
<p>In order to use the <code>within</code> operator, a geo index must be defined for the collection. This index also defines which attribute holds the coordinates for the document. If you have more then one geo-spatial index, you can use the <code>geo</code> field to select a particular index.</p>
<p>The call expects a JSON hash array as body with the following attributes:</p>
<ul>
<li><code>collection</code>: The identifier or name of the collection to query.</li>
</ul>
<ul>
<li><code>latitude</code>: The latitude of the coordinate.</li>
</ul>
<ul>
<li><code>longitude</code>: The longitude of the coordinate.</li>
</ul>
<ul>
<li><code>radius</code>: The maximal radius (in meters).</li>
</ul>
<ul>
<li><code>distance</code>: If given, the result attribute key used to store the distance values (optional). If specified, distances are returned in meters.</li>
</ul>
<ul>
<li><code>skip</code>: The documents to skip in the query. (optional)</li>
</ul>
<ul>
<li><code>limit</code>: The maximal amount of documents to return. (optional)</li>
</ul>
<ul>
<li><code>geo</code>: If given, the identifier of the geo-index to use. (optional)</li>
</ul>
<p>Returns a cursor containing the result, see <a class="el" href="HttpCursor.html">HTTP Interface for AQL Query Cursors</a> for details.</p>
<p><b>Examples</b><br/>
</p>
<p>Without distance:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/within
{ "collection" : "2076584128", "latitude" : 0, "longitude" : 0, "skip" : 1, "radius" : 1111950 }
HTTP/1.1 201 Created
content-type: application/json
{
"result": [
{
"_id": "2076584128/2082744512",
"loc": [ 10, 0 ],
"_rev": 2082744512
},
{
"_id": "2076584128/2082089152",
"loc": [ 0, 10 ],
"_rev": 2082089152
},
{
"_id": "2076584128/2081302720",
"loc": [ -10, 0 ],
"_rev": 2081302720
},
{
"_id": "2076584128/2081958080",
"loc": [ 0, -10 ],
"_rev": 2081958080
}
],
"code": 201,
"hasMore": false,
"count": 4,
"error": false
}
</pre></div><p>With distance:</p>
<div class="fragment"><pre class="fragment">&gt; curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/within
{ "collection" : "2086152384", "latitude" : 0, "longitude" : 0, "distance" : "distance", "radius" : 1111950 }
HTTP/1.1 201 Created
content-type: application/json
{
"result": [
{
"distance": 0,
"_id": "2086152384/2091591872",
"loc": [ 0, 0 ],
"_rev": 2091591872
},
{
"distance": 1111949.26644559,
"_id": "2086152384/2090870976",
"loc": [ -10, 0 ],
"_rev": 2090870976
},
{
"distance": 1111949.26644559,
"_id": "2086152384/2091657408",
"loc": [ 0, 10 ],
"_rev": 2091657408
},
{
"distance": 1111949.26644559,
"_id": "2086152384/2092312768",
"loc": [ 10, 0 ],
"_rev": 2092312768
},
{
"distance": 1111949.26644559,
"_id": "2086152384/2091526336",
"loc": [ 0, -10 ],
"_rev": 2091526336
}
],
"code": 201,
"hasMore": false,
"count": 5,
"error": false
}
</pre></div> </div></div>
</div></body></html>
Reference in New Issue View Git Blame Copy Permalink