Managing Geolocations

With the Kii Cloud SDK, you can store geolocations in a JSON document and query data by geolocation.

Geolocation representation

In Kii Cloud, a geolocation is defined with GeoPoint, a data type for values to be stored in a JSON document.

A geolocation can be set as a GeoPoint that has latitude and longitude coordinates. A GeoPoint can be used as a value for a key, for example, location in the figure below. Note that the geolocation in this diagram is represented in the JSON format that is used with the REST API, the developer portal, and so on. With the Kii Cloud SDK, a geolocation is specified with the GeoPoint class for Android and the KiiGeoPoint class for the other platforms.

A KiiObject can have any number of geolocations. For example, you can define a KiiObject that represents the entrance and exit of a tunnel with two GeoPoints, entrance and exit.

Latitude and longitude coordinates can be stored in a KiiObject with two fields of real number. On the other hand, if those values are held in a GeoPoint, you can use the query feature described in the next section. Geolocation data enables you to perform a query beyond a simple comparison because a geolocation is represented in two-dimensional space.

For more information about setting and getting a GeoPoint, see Setting a Key-value Pair and Getting a Key-value Pair.

Query feature

You can query KiiObjects by geolocation in the following two methods. These methods can be combined with other query conditions, for example, that returns KiiObjects such that the score key of each KiiObject has a value greater than 70.

• GeoBox query

  This query returns KiiObjects that are in a rectangular area specified by two pairs of latitude and longitude coordinates.

  For example, you can perform a query with a condition that returns KiiObjets such that:

  • The location key of each KiiObject is within an area specified by coordinates lat1 and lon1, and lat2 and lon2

    AND

  • The above_sea_level key of each KiiObject has a value greater than or equal to 10.

• GeoDistance query

  This query returns KiiObjects that are in a circular area specified by the center and radius of the circle.

  For example, you can perform a query with a condition that returns KiiObjects such that:

  • The location key of each KiiObject is within a 2km radius of the center specified by coordinates lat1 and lon2

    AND

  • The above_sea_level key of each KiiObject has a value greater than or equal to 10.

For more information about querying by geolocation, see Querying KiiObjects.