ArangoDB v3.4 reached End of Life (EOL) and is no longer supported.

This documentation is outdated. Please see the most recent version here: Latest Docs

Working with Geo Indexes

Create geo-spatial index

creates a geo index

POST /_api/index

Query Parameters

collection (string, required): The collection name.

Request Body

type (string, required): must be equal to “geo”.
fields (array of strings, required): An array with one or two attribute paths.

If it is an array with one attribute path location, then a geo-spatial index on all documents is created using location as path to the coordinates. The value of the attribute must be an array with at least two double values. The array 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.

If it is an array with two attribute paths latitude and longitude, then a geo-spatial index on all documents is created using latitude and longitude as paths the latitude and the longitude. The value of the attribute latitude and of the attribute longitude must a double. All documents, which do not have the attribute paths or which values are not suitable, are ignored.
geoJson (string, required): If a geo-spatial index on a location is constructed and geoJson is true, then the order within the array is longitude followed by latitude. This corresponds to the format described in http://geojson.org/geojson-spec.html#positions

NOTE Swagger examples won’t work due to the anchor.

Creates a geo-spatial index in the collection collection-name, if it does not already exist. Expects an object containing the index details.

Geo indexes are always sparse, meaning that documents that do not contain the index attributes or have non-numeric values in the index attributes will not be indexed.

Responses

HTTP 200: If the index already exists, then a HTTP 200 is returned.

HTTP 201: If the index does not already exist and could be created, then a HTTP 201 is returned.

HTTP 404: If the collection-name is unknown, then a HTTP 404 is returned.

Examples

Creating a geo index with a location attribute

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/index?collection=products <<EOF
{ 
  "type" : "geo", 
  "fields" : [ 
    "b" 
  ] 
}
EOF

HTTP/1.1 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "bestIndexedLevel" : 17, 
  "fields" : [ 
    "b" 
  ], 
  "geoJson" : false, 
  "id" : "products/69757", 
  "isNewlyCreated" : true, 
  "maxNumCoverCells" : 8, 
  "sparse" : true, 
  "type" : "geo", 
  "unique" : false, 
  "worstIndexedLevel" : 4, 
  "error" : false, 
  "code" : 201 
}

Hide response body

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/index?collection=products <<EOF
{ 
  "type" : "geo", 
  "fields" : [ 
    "b" 
  ] 
}
EOF

HTTP/1.1 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

Show response body

Creating a geo index with latitude and longitude attributes

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/index?collection=products <<EOF
{ 
  "type" : "geo", 
  "fields" : [ 
    "e", 
    "f" 
  ] 
}
EOF

HTTP/1.1 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "bestIndexedLevel" : 17, 
  "fields" : [ 
    "e", 
    "f" 
  ], 
  "geoJson" : false, 
  "id" : "products/69747", 
  "isNewlyCreated" : true, 
  "maxNumCoverCells" : 8, 
  "sparse" : true, 
  "type" : "geo", 
  "unique" : false, 
  "worstIndexedLevel" : 4, 
  "error" : false, 
  "code" : 201 
}

Hide response body

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/index?collection=products <<EOF
{ 
  "type" : "geo", 
  "fields" : [ 
    "e", 
    "f" 
  ] 
}
EOF

HTTP/1.1 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

Show response body

Returns documents near a coordinate

returns all documents of a collection near a given location

PUT /_api/simple/near

This route should no longer be used. All endpoints for Simple Queries are deprecated from version 3.4.0 on. They are superseded by AQL queries.

Request Body

collection (string, required): The name of the collection to query.
latitude (string, required): The latitude of the coordinate.
longitude (string, required): The longitude of the coordinate.
distance (string, required): If given, the attribute key used to return the distance to the given coordinate. (optional). If specified, distances are returned in meters.
skip (string, required): The number of documents to skip in the query. (optional)
limit (string, required): The maximal amount of documents to return. The skip is applied before the limit restriction. The default is 100. (optional)
geo (string, required): If given, the identifier of the geo-index to use. (optional)

The default will find at most 100 documents near the given coordinate. The returned array is sorted according to the distance, with the nearest document being first in the return array. If there are near documents of equal distance, documents are chosen randomly from this set until the limit is reached.

In order to use the near 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 than one geo-spatial index, you can use the geo field to select a particular index.

Returns a cursor containing the result, see HTTP Cursor for details.

Note: the near simple query is deprecated as of ArangoDB 2.6. This API may be removed in future versions of ArangoDB. The preferred way for retrieving documents from a collection using the near operator is to issue an AQL query using the NEAR function as follows:

FOR doc IN NEAR(@@collection, @latitude, @longitude, @limit)
  RETURN doc`

Responses

HTTP 201: is returned if the query was executed successfully.

HTTP 400: is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case.

HTTP 404: is returned if the collection specified by collection is unknown. The response body contains an error document in this case.

Examples

Without distance

shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/simple/near <<EOF
{ 
  "collection" : "products", 
  "latitude" : 0, 
  "longitude" : 0, 
  "skip" : 1, 
  "limit" : 2 
}
EOF

HTTP/1.1 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "result" : [ 
    { 
      "_key" : "70123", 
      "_id" : "products/70123", 
      "_rev" : "_bHcRMea--A", 
      "name" : "Name/-0.002/", 
      "loc" : [ 
        -0.002, 
        0 
      ] 
    }, 
    { 
      "_key" : "70127", 
      "_id" : "products/70127", 
      "_rev" : "_bHcRMee--A", 
      "name" : "Name/0.002/", 
      "loc" : [ 
        0.002, 
        0 
      ] 
    } 
  ], 
  "hasMore" : false, 
  "count" : 2, 
  "error" : false, 
  "code" : 201 
}

Hide response body

shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/simple/near <<EOF
{ 
  "collection" : "products", 
  "latitude" : 0, 
  "longitude" : 0, 
  "skip" : 1, 
  "limit" : 2 
}
EOF

HTTP/1.1 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

Show response body

With distance

shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/simple/near <<EOF
{ 
  "collection" : "products", 
  "latitude" : 0, 
  "longitude" : 0, 
  "skip" : 1, 
  "limit" : 3, 
  "distance" : "distance" 
}
EOF

HTTP/1.1 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "result" : [ 
    { 
      "_id" : "products/70158", 
      "_key" : "70158", 
      "_rev" : "_bHcRMf2---", 
      "loc" : [ 
        -0.002, 
        0 
      ], 
      "name" : "Name/-0.002/", 
      "distance" : 222.3898532891175 
    }, 
    { 
      "_id" : "products/70162", 
      "_key" : "70162", 
      "_rev" : "_bHcRMf6---", 
      "loc" : [ 
        0.002, 
        0 
      ], 
      "name" : "Name/0.002/", 
      "distance" : 222.3898532891175 
    }, 
    { 
      "_id" : "products/70164", 
      "_key" : "70164", 
      "_rev" : "_bHcRMg----", 
      "loc" : [ 
        0.004, 
        0 
      ], 
      "name" : "Name/0.004/", 
      "distance" : 444.779706578235 
    } 
  ], 
  "hasMore" : false, 
  "count" : 3, 
  "error" : false, 
  "code" : 201 
}

Hide response body

shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/simple/near <<EOF
{ 
  "collection" : "products", 
  "latitude" : 0, 
  "longitude" : 0, 
  "skip" : 1, 
  "limit" : 3, 
  "distance" : "distance" 
}
EOF

HTTP/1.1 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

Show response body

Find documents within a radius around a coordinate

returns all documents of a collection within a given radius

PUT /_api/simple/within

This route should no longer be used. All endpoints for Simple Queries are deprecated from version 3.4.0 on. They are superseded by AQL queries.

Request Body

collection (string, required): The name of the collection to query.
latitude (string, required): The latitude of the coordinate.
longitude (string, required): The longitude of the coordinate.
radius (string, required): The maximal radius (in meters).
distance (string, required): If given, the attribute key used to return the distance to the given coordinate. (optional). If specified, distances are returned in meters.
skip (string, required): The number of documents to skip in the query. (optional)
limit (string, required): The maximal amount of documents to return. The skip is applied before the limit restriction. The default is 100. (optional)
geo (string, required): If given, the identifier of the geo-index to use. (optional)

This will find all documents within a given radius around the coordinate (latitude, longitude). The returned list is sorted by distance.

In order to use the within 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 than one geo-spatial index, you can use the geo field to select a particular index.

Returns a cursor containing the result, see HTTP Cursor for details.

Note: the within simple query is deprecated as of ArangoDB 2.6. This API may be removed in future versions of ArangoDB. The preferred way for retrieving documents from a collection using the near operator is to issue an AQL query using the WITHIN function as follows:

FOR doc IN WITHIN(@@collection, @latitude, @longitude, @radius, @distanceAttributeName)
  RETURN doc

Responses

HTTP 201: is returned if the query was executed successfully.

HTTP 400: is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case.

HTTP 404: is returned if the collection specified by collection is unknown. The response body contains an error document in this case.

Examples

Without distance

shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/simple/near <<EOF
{ 
  "collection" : "products", 
  "latitude" : 0, 
  "longitude" : 0, 
  "skip" : 1, 
  "limit" : 2, 
  "radius" : 500 
}
EOF

HTTP/1.1 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "result" : [ 
    { 
      "_key" : "70361", 
      "_id" : "products/70361", 
      "_rev" : "_bHcRMre--A", 
      "name" : "Name/-0.002/", 
      "loc" : [ 
        -0.002, 
        0 
      ] 
    }, 
    { 
      "_key" : "70365", 
      "_id" : "products/70365", 
      "_rev" : "_bHcRMri--A", 
      "name" : "Name/0.002/", 
      "loc" : [ 
        0.002, 
        0 
      ] 
    } 
  ], 
  "hasMore" : false, 
  "count" : 2, 
  "error" : false, 
  "code" : 201 
}

Hide response body

shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/simple/near <<EOF
{ 
  "collection" : "products", 
  "latitude" : 0, 
  "longitude" : 0, 
  "skip" : 1, 
  "limit" : 2, 
  "radius" : 500 
}
EOF

HTTP/1.1 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

Show response body

With distance

shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/simple/near <<EOF
{ 
  "collection" : "products", 
  "latitude" : 0, 
  "longitude" : 0, 
  "skip" : 1, 
  "limit" : 3, 
  "distance" : "distance", 
  "radius" : 300 
}
EOF

HTTP/1.1 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "result" : [ 
    { 
      "_id" : "products/70396", 
      "_key" : "70396", 
      "_rev" : "_bHcRMs2---", 
      "loc" : [ 
        -0.002, 
        0 
      ], 
      "name" : "Name/-0.002/", 
      "distance" : 222.3898532891175 
    }, 
    { 
      "_id" : "products/70400", 
      "_key" : "70400", 
      "_rev" : "_bHcRMs6--A", 
      "loc" : [ 
        0.002, 
        0 
      ], 
      "name" : "Name/0.002/", 
      "distance" : 222.3898532891175 
    }, 
    { 
      "_id" : "products/70402", 
      "_key" : "70402", 
      "_rev" : "_bHcRMt----", 
      "loc" : [ 
        0.004, 
        0 
      ], 
      "name" : "Name/0.004/", 
      "distance" : 444.779706578235 
    } 
  ], 
  "hasMore" : false, 
  "count" : 3, 
  "error" : false, 
  "code" : 201 
}

Hide response body

shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/simple/near <<EOF
{ 
  "collection" : "products", 
  "latitude" : 0, 
  "longitude" : 0, 
  "skip" : 1, 
  "limit" : 3, 
  "distance" : "distance", 
  "radius" : 300 
}
EOF

HTTP/1.1 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

Show response body

❮ Persistent Fulltext ❯