Skip to content

Search in Category

This API supports two types of geo searches:

  • Search in one or more geo categories.
  • Search based on metadata properties in one or more categories .

Method

GET

URL

https://api.backendless.com/<application-id>/<REST-api-key>/geo/points?  
categories=<categories>&  
where=<where>&  
metadata=<metadata>&  
pagesize=<pagesize>&  
includemetadata=<includemetadata>&  
offset=<offset> 

where:

Argument                Description
<application id> ID of the application which can be obtained from the Manage > App Settings screen of the Backendless Console
<REST-api-key> REST API key of your application. You can get the value from the Manage > App Settings section of the Backendless Console.
<categories> list of categories separated by comma where to run the search. If the parameter is not present in the request, the search is ran in the "Default" category.
<where> contains an SQL query (the where clause part) which is used to search for the objects. The value must be URL encoded.
<metadata> metadata which must match in order for a point to be selected for the search result. Must be expressed in as a URL encoded JSON object. For example, { "foo":"bar" } will be URL encoded as:  %20%7B%20%22foo%22%3A%22bar%22%20%7D. Found geo points must match the specified metadata key/value pairs entirely. See partial match search for the search API that does not require complete matches. Accepted values for this parameter are: String, Number (integer and double), and Data Service objects. Date values must be represented as number in the Unix timestamp format (number of milliseconds since January 1, 1970 at UTC). Learn more about using date in search queries for category, radius, or rectangular area search.
<pagesize> number of geo points to be returned in the response.
<includemetadata> Boolean value indicating whether geo point metadata should be included in the response. Supported values are true or false.
<offset> sequential (zero-based) index from where to run the search. For example, suppose the first search query returned 50 geo points (pageSize is set to 50). A subsequent search should set the offset value to 50 in order to get the next page of search results.

Request headers

user-token: optional value obtained as a result of the login operation.

where:

Argument                Description
user-token Optional header. Contains a value returned by Backendless in a preceding user Login API call. If user-token is set in the request, the currently logged in user will be assigned to the ownerId property of the user object which is being saved.  Additionally, the operation will be executed with the security policy associated currently logged in user. This means all permissions associated with the user and the roles assigned to the user will be enforced by Backendless.

Request Body

none

Response Body

A JSON array of geopoint objects. Each object contains the following properties:

Argument                Description
objectId an ID assigned to a geo point by Backendless.
latitude geo point's latitude coordinate
longitude geo point's longitude coordinate
categories an array of categories the geo point belongs to
metadata a JSON object of key/value pairs describing geo point's metadata properties

Since the search query may produce a large number of geo points, not all of them are returned at once. Instead, all found geo points are divided into 'pages'. The size of each page is determined by the pageSize parameter in the query. The first response returns the first page. Subsequent search requests with the modified offset will return additional pages of data.

Calculating offset

All geo points in the entire search result are indexed. The index of the first geo point is 0. The offset parameter in the query specifies the index from which to load the next page of geo points. For example, suppose the entire search result is 200 points. If the initial pageSize is 20, then only 20 geo points are returned in the first response. To get the second page of geo points, they should be loaded from offset 20, third from 40 and so on. The formula for calculating offset is:

[value of offset in the current response] + [size of current page ].

If an error occurs, the response is formatted as described in the Error Handling section. Below is a sample response:

[  
  {  
   "objectId": "609CEE02-174E-2486-FFD1-2AAE48B89100",  
   "latitude": 41,  
   "longitude": 2,  
   "categories": [  
     "Restaurants"  
   ],  
   "metadata": {  
     "foo": "bar"  
   }  
  },  
  {  
    "objectId": "80ED18EB-D53B-5E68-FFC0-EA341C213F00",  
    "latitude": 41,  
    "longitude": -87,  
    "categories": [  
      "Restaurants"  
    ],  
    "metadata": {  
      "foo": "bar"  
    }  
    }  
]

Running Search Queries

The geo query object includes multiple parameters. Depending on which parameters contain values, the semantics of the search would change. Any search must be performed within at least one category. If no category names are provided, the search is performed in the Default category.

Search in categories

To search in one or more categories without any constraints on metadata or proximity to a center point, simply set the names of the categories in the query object. The request returns all geo points divided into pages of data, one page at a time.  
curl -X GET \  
-v "http://api.backendless.com/XXXX-XXXX-XXXX/ZZZZ-ZZZZ-ZZZZ/geo/points?categories=Restaurants"

Search in categories with metadata

Metadata-based search finds all geo points which match all specified metadata properties in the given categories. The example below searches for the geo points in the Restaurants category with metadata containing "Cuisine = French" and "Atmosphere = Romantic".

curl -X GET \  
-v "http://api.backendless.com/XXXX-XXXX-XXXX/ZZZZ-ZZZZ-ZZZZ/geo/points?categories=Restaurants&metadata=%7B%22Cuisine%22%3A%22French%22%2C%20%22Atmosphere%22%3A%22Romantic%22%7D"


Using dates in where clause when searching in categories

The search query used to retrieve geo points may reference date values. These values must be stored as a number of milliseconds since January 1st, 1970 at UTC. The example below demonstrates the usage of a date/time timestamp in a search query:

curl -X GET \  
-v "[http://api.backendless.com/](http://api.backendless.com/)XXXX-XXXX-XXXX/ZZZZ-ZZZZ-ZZZZ[/geo/points?categories=Restaurants?where=](/geo/points?categories=Restaurants?where=)updated<1421234854999"

Requesting meta in response

Geo points returned in the search results do not include their metadata properties by default. The search query object includes a property which can be used to request the metadata to be included. This property can be used with any search options described above. For example, the following code runs a search in a category and requests the metadata to be included:

curl -X GET \  
-v "http://api.backendless.com/XXXX-XXXX-XXXX/ZZZZ-ZZZZ-ZZZZ/geo/points?categories=Restaurants&includemetadata=true"

Search by using the IN operator

Use IN operator to search for the objects in several locations. For instance, to find all objects located in Dallas, Kyiv, or Lviv specify the following  values for where parameter: city in ('DALLAS','KYIV','LVIV'). The value of where parameter should be URL-encoded. Values in the parenthesis define the locations, for which you will be searching. If a location value matches any of the values in the parenthesis, the location will be included into the search response.

curl -X GET \  
-v "[http://api.backendless.com/](http://api.backendless.com/)XXXX-XXXX-XXXX/ZZZZ-ZZZZ-ZZZZ[/geo/points?categories=geoservice_sample&where=city%20in%20(%27DALLAS%27%2C%27KYIV%27%2C%27LVIV%27)&includemetadata=true](/geo/points?categories=geoservice_sample&where=city%20in%20(%27DALLAS%27%2C%27KYIV%27%2C%27LVIV%27)&includemetadata=true)"