Working with Geo Indexes

Create geo-spatial index

creates a geo index

POST /_api/index#geo

Query Parameters

  • collection (required): The collection name.

A JSON object with these properties is required:

  • fields (string): 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.
  • type: must be equal to "geo".
  • geoJson: 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.

Example:

Creating a geo index with a location attribute

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

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

{ 
  "constraint" : false, 
  "fields" : [ 
    "b" 
  ], 
  "geoJson" : false, 
  "id" : "products/11812", 
  "ignoreNull" : true, 
  "isNewlyCreated" : true, 
  "sparse" : true, 
  "type" : "geo1", 
  "unique" : false, 
  "error" : false, 
  "code" : 201 
}

Example:

Creating a geo index with latitude and longitude attributes

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

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

{ 
  "constraint" : false, 
  "fields" : [ 
    "e", 
    "f" 
  ], 
  "id" : "products/11798", 
  "ignoreNull" : true, 
  "isNewlyCreated" : true, 
  "sparse" : true, 
  "type" : "geo2", 
  "unique" : false, 
  "error" : false, 
  "code" : 201 
}

Return Codes

  • 200: If the index already exists, then a HTTP 200 is returned.
  • 201: If the index does not already exist and could be created, then a HTTP 201 is returned.
  • 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 --data-binary @- --dump - http://localhost:8529/_api/index?collection=products <<EOF
{ 
  "type" : "geo", 
  "fields" : [ 
    "b" 
  ] 
}
EOF

HTTP/1.1 201 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 --data-binary @- --dump - http://localhost:8529/_api/index?collection=products <<EOF
{ 
  "type" : "geo", 
  "fields" : [ 
    "e", 
    "f" 
  ] 
}
EOF

HTTP/1.1 201 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

A JSON object with these properties is required:

  • distance: If given, the attribute key used to return the distance to the given coordinate. (optional). If specified, distances are returned in meters.
  • skip: The number of documents to skip in the query. (optional)
  • longitude: The longitude of the coordinate.
  • limit: The maximal amount of documents to return. The skip is applied before the limit restriction. The default is 100. (optional)
  • collection: The name of the collection to query.
  • latitude: The latitude of the coordinate.
  • geo: 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`

Example:

Without distance

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

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

{ 
  "result" : [ 
    { 
      "_key" : "12441", 
      "_id" : "products/12441", 
      "_rev" : "_WQ47fgq--D", 
      "name" : "Name/0.002/", 
      "loc" : [ 
        0.002, 
        0 
      ] 
    }, 
    { 
      "_key" : "12435", 
      "_id" : "products/12435", 
      "_rev" : "_WQ47fgq--_", 
      "name" : "Name/-0.002/", 
      "loc" : [ 
        -0.002, 
        0 
      ] 
    } 
  ], 
  "hasMore" : false, 
  "count" : 2, 
  "error" : false, 
  "code" : 201 
}

Example:

With distance

shell> curl -X PUT --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 201 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "result" : [ 
    { 
      "distance" : 222.38985328911744, 
      "_id" : "products/12486", 
      "_key" : "12486", 
      "_rev" : "_WQ47fhq--D", 
      "loc" : [ 
        -0.002, 
        0 
      ], 
      "name" : "Name/-0.002/" 
    }, 
    { 
      "distance" : 222.38985328911744, 
      "_id" : "products/12492", 
      "_key" : "12492", 
      "_rev" : "_WQ47fhq--H", 
      "loc" : [ 
        0.002, 
        0 
      ], 
      "name" : "Name/0.002/" 
    }, 
    { 
      "distance" : 444.779706578235, 
      "_id" : "products/12483", 
      "_key" : "12483", 
      "_rev" : "_WQ47fhq--B", 
      "loc" : [ 
        -0.004, 
        0 
      ], 
      "name" : "Name/-0.004/" 
    } 
  ], 
  "hasMore" : false, 
  "count" : 3, 
  "error" : false, 
  "code" : 201 
}

Return Codes

  • 201: is returned if the query was executed successfully.
  • 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.
  • 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 --data-binary @- --dump - http://localhost:8529/_api/simple/near <<EOF
{ 
  "collection" : "products", 
  "latitude" : 0, 
  "longitude" : 0, 
  "skip" : 1, 
  "limit" : 2 
}
EOF

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

With distance

shell> curl -X PUT --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 201 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

A JSON object with these properties is required:

  • distance: If given, the attribute key used to return the distance to the given coordinate. (optional). If specified, distances are returned in meters.
  • skip: The number of documents to skip in the query. (optional)
  • longitude: The longitude of the coordinate.
  • radius: The maximal radius (in meters).
  • collection: The name of the collection to query.
  • latitude: The latitude of the coordinate.
  • limit: The maximal amount of documents to return. The skip is applied before the limit restriction. The default is 100. (optional)
  • geo: 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

Example:

Without distance

shell> curl -X PUT --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 201 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "result" : [ 
    { 
      "_key" : "12854", 
      "_id" : "products/12854", 
      "_rev" : "_WQ47foi--_", 
      "name" : "Name/0.002/", 
      "loc" : [ 
        0.002, 
        0 
      ] 
    }, 
    { 
      "_key" : "12848", 
      "_id" : "products/12848", 
      "_rev" : "_WQ47foe--H", 
      "name" : "Name/-0.002/", 
      "loc" : [ 
        -0.002, 
        0 
      ] 
    } 
  ], 
  "hasMore" : false, 
  "count" : 2, 
  "error" : false, 
  "code" : 201 
}

Example:

With distance

shell> curl -X PUT --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 201 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "result" : [ 
    { 
      "distance" : 222.38985328911744, 
      "_id" : "products/12899", 
      "_key" : "12899", 
      "_rev" : "_WQ47fpW--B", 
      "loc" : [ 
        -0.002, 
        0 
      ], 
      "name" : "Name/-0.002/" 
    }, 
    { 
      "distance" : 222.38985328911744, 
      "_id" : "products/12905", 
      "_key" : "12905", 
      "_rev" : "_WQ47fpW--F", 
      "loc" : [ 
        0.002, 
        0 
      ], 
      "name" : "Name/0.002/" 
    }, 
    { 
      "distance" : 444.779706578235, 
      "_id" : "products/12896", 
      "_key" : "12896", 
      "_rev" : "_WQ47fpW--_", 
      "loc" : [ 
        -0.004, 
        0 
      ], 
      "name" : "Name/-0.004/" 
    } 
  ], 
  "hasMore" : false, 
  "count" : 3, 
  "error" : false, 
  "code" : 201 
}

Return Codes

  • 201: is returned if the query was executed successfully.
  • 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.
  • 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 --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 201 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body

With distance

shell> curl -X PUT --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 201 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body

© ArangoDB - the native multi-model NoSQL database