4.3 KiB
//////////////////////////////////////////////////////////////////////////////// /// @startDocuBlock JSA_put_api_simple_within /// @brief returns all documents of a collection within a given radius /// /// @RESTHEADER{PUT /_api/simple/within, Find documents within a radius around a coordinate} /// /// @RESTBODYPARAM{collection,string,required,string} /// The name of the collection to query. /// /// @RESTBODYPARAM{latitude,string,required,string} /// The latitude of the coordinate. /// /// @RESTBODYPARAM{longitude,string,required,string} /// The longitude of the coordinate. /// /// @RESTBODYPARAM{radius,string,required,string} /// The maximal radius (in meters). /// /// @RESTBODYPARAM{distance,string,required,string} /// If given, the attribute key used to return the distance to /// the given coordinate. (optional). If specified, distances are returned in meters. /// /// @RESTBODYPARAM{skip,string,required,string} /// The number of documents to skip in the query. (optional) /// /// @RESTBODYPARAM{limit,string,required,string} /// The maximal amount of documents to return. The skip is /// applied before the limit restriction. The default is 100. (optional) /// /// @RESTBODYPARAM{geo,string,required,string} /// If given, the identifier of the geo-index to use. (optional) /// /// @RESTDESCRIPTION /// /// 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 /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{201} /// is returned if the query was executed successfully. /// /// @RESTRETURNCODE{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. /// /// @RESTRETURNCODE{404} /// is returned if the collection specified by collection is unknown. The /// response body contains an error document in this case. /// /// @EXAMPLES /// /// Without distance /// /// @EXAMPLE_ARANGOSH_RUN{RestSimpleWithin} /// var cn = "products"; /// db._drop(cn); /// var products = db._create(cn); /// var loc = products.ensureGeoIndex("loc"); /// var i; /// for (i = -0.01; i <= 0.01; i += 0.002) { /// products.save({ name : "Name/" + i + "/",loc: [ i, 0 ] }); /// } /// var url = "/_api/simple/near"; /// var body = { /// "collection": "products", /// "latitude" : 0, /// "longitude" : 0, /// "skip" : 1, /// "limit" : 2, /// "radius" : 500 /// }; /// /// var response = logCurlRequest('PUT', url, body); /// /// assert(response.code === 201); /// /// logJsonResponse(response); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN /// /// With distance /// /// @EXAMPLE_ARANGOSH_RUN{RestSimpleWithinDistance} /// var cn = "products"; /// db._drop(cn); /// var products = db._create(cn); /// var loc = products.ensureGeoIndex("loc"); /// var i; /// for (i = -0.01; i <= 0.01; i += 0.002) { /// products.save({ name : "Name/" + i + "/",loc: [ i, 0 ] }); /// } /// var url = "/_api/simple/near"; /// var body = { "collection": "products", "latitude" : 0, "longitude" : 0, /// "skip" : 1, "limit" : 3, "distance" : "distance", "radius" : 300 }; /// /// var response = logCurlRequest('PUT', url, body); /// /// assert(response.code === 201); /// /// logJsonResponse(response); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN /// @endDocuBlock ////////////////////////////////////////////////////////////////////////////////