ArangoDB Logo

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

This documentation is outdated. Please see the most recent stable version.

HTTP interface for geo-spatial indexes

Create a geo-spatial index

POST /_db/{database-name}/_api/index

Creates a geo-spatial index in the collection collection, if it does not already exist.

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.

Path Parameters

  • The name of the database.

Query Parameters

  • The collection name.

HTTP Headers
    Request Body application/json object

    • 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 values of the latitude and longitude attributes must each be a number (double). All documents which do not have the attribute paths or which have values that are not suitable are ignored.

    • If you create a geo-spatial index over a single attribute and geoJson is true, then the coordinate order within the attribute’s array is longitude followed by latitude. This corresponds to the format described in http://geojson.org/geojson-spec.html#positions 

    • Set this option to true to keep the collection/shards available for write operations by not using an exclusive write lock for the duration of the index creation.

    • If geoJson is set to true, then this option controls how GeoJSON Polygons are interpreted.

      • If legacyPolygons is true, the smaller of the two regions defined by a linear ring is interpreted as the interior of the ring and a ring can at most enclose half the Earth’s surface.
      • If legacyPolygons is false, the area to the left of the boundary ring’s path is considered to be the interior and a ring can enclose the entire surface of the Earth.

      The default is true for geo indexes that were created in versions before 3.10, and false for geo indexes created in 3.10 or later.

    • An easy-to-remember name for the index to look it up or refer to it in index hints. Index names are subject to the same character restrictions as collection names. If omitted, a name is auto-generated so that it is unique with respect to the collection, e.g. idx_832910498.

    • Must be equal to "geo".

    Responses

    • The index exists already.

    • The index is created as there is no such existing index.

    • The collection is unknown.

    Examples

    Creating a geo index with a location attribute

    curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/index?collection=products' <<'EOF'
{
  "type": "geo",
  "fields": [
    "b"
  ]
}
EOF
    Show output
    HTTP/1.1 201 Created
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 264
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

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

    Creating a geo index with latitude and longitude attributes

    curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/index?collection=products' <<'EOF'
{
  "type": "geo",
  "fields": [
    "e",
    "f"
  ]
}
EOF
    Show output
    HTTP/1.1 201 Created
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 268
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

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