Skip to content

Relations with Geo Points

Backendless Geo Service manages application's geo location data and provides APIs to work with Geo points. Backendless supports integration between data objects managed by Data Service and geo points for the scenarios when a logical connection between the two entity types must exist in an application. For instance, in a taxi ordering application a data object may represent a taxi car, while a geo point represents its location on the map. Linking the two entity types together provides great benefits such as retrieving both objects at once and managing as a consistent, cohesive object hierarchy.

The Data-to-Geo integration is implemented through object relations. Data table schema may declare a table column with a special data type - "GeoPoint Relationship". As a result, the data objects in the table may contain a reference to one or more GeoPoints. When a data object with a related GeoPoint is saved, Backendless persists information about both the data object and the geo point in the corresponding persistent systems and sets up the relationship. Likewise, when a data object is retrieved by using the API, any related geo points can be retrieved using the same principle for loading data relations. The data-to-geo relation is bidirectional, it means a geo point may reference a data object in its metadata. You can learn more about it in the Relations with Data Objects section of the Geolocation documentation.

The relationship between a data object and a geo point (or a collection of) can be established by using either the "code first" or the "schema first" approaches. With the former, the relationship is determined by the data structure persisted with the API. If a data object references a GeoPoint (or a collection of) in one of its properties, Backendless interprets it as a relation and, as a result, will create a relation column in the data table schema. With the latter ("schema first") approach, application developer can declare a relationship in the data table schema first. In either one of these approaches, once a relationship is declared, data objects and geo points may be linked together by using the Backendless console as well.

This chapter consists of the following sections:

Declaring a Data-to-Geo Relationship in Table Schema

Linking a Data Object with Geo Points

Update/Delete Relations

Deleting Relation Column in Table Schema

Establishing Relations with Geo Points via API

Declaring a Data-to-Geo Relationship in Table Schema

To declare a relationship in a data table schema:

  1. Select a table where a relation column should be declared.
  2. Click the Schema menu.
  3. Click the New button. Enter a name for the new column in the Name field. This column will represent a data-to-geo relationship.
  4. Select the Geopoint Relationship option from the Type drop-down list.

  5. Select the constraints and/or cardinality of the relation from the corresponding drop-down menus.

    There are two available constraints: "Not Null (Required)" and "Unique Value". The former (NN) establishes the column as required. It means when a new object is created or an existing one is updated, server will be expecting a value for the column. The latter constraint (UQ) will enforce a rule that the column must contain a unique value, thus no two objects will be able to contain the same GeoPoint.

    The one-to-one relation means that a table's object can be linked with only one geo point, while the one-to-many relation means that a table's object can be linked with multiple geo points.

  6. Click the CREATE button to save the changes.

Linking a Data Object with Geo Points

Once a data-to-geo relationship column is declared, data objects from the table can be linked to geo point(s) as described below:

  1. Click the name of the table containing an object you want to link with a geo point.
  2. Table columns representing the data-to-geo relationships are identified as "GEOPOINT relationship" in the header row. The cardinality of the relation is visualized as one red line for the one-to-one relations and three red lines for the one-to-many relations:
  3. To create a relationship between an object and a geopoint, click the plus icon next in the cell for a GEOPOINT column.
  4. The Set Related GeoPoint pop-up window will display the list of the geo points. Use the Geo Category drop-down list to select a geo category from which the points should be displayed. Additionally, you can use the search bar to locate a geopoint by its metadata:
  5. If you declared a one-to-one relation for a table the object belongs to, you will be able to link this object with only one geo point (by the means of a radio button). If it is a one-to-many relationship, the interface uses check boxes, which allow for multiple selection. Click a radio-button or select check-boxes next to the geo points which you want to link with the data object.
  6. Click the ADD RELATION button to save the changes.

Once a relation is established, it is shown in the data browser as a hyperlink. The hyperlink for the one-to-one relations displays the coordinates of the related geo point. For the one-to-many relations the link says "multiple Geopoints". In both cases, the link opens the Geolocation screen of the console which displays the related geo point(s). Additionally, the link has a mouse-over preview for the related geopoints:


Update/Delete Relations

To update a data-to-geo relation, use the same plus icon that opened the popup to create a geopoint relation. The popup tracks the selection changes and allows update or deletion of the relation.

Deleting Relation Column in Table Schema

A data-to-geo relationship can be removed at the schema level. When a relationship column is removed, the "links" between the corresponding data objects and geopoints are deleted, however, it does not remove the objects themselves.

To delete a relationship definition between a data table and the geo points:

  1. Click the name of the table which contains a "GeoPoint relationship" column you need to remove.
  2. Click the Schema menu
  3. Click the check-box next to the column you need to delete.
  4. Click the Delete menu.

Establishing Relations with Geo Points via API

Creating a relationship between a data object and a geo point (or a collection of) uses the same API as saving a data object with a related entity. In the case of data-to-geo relations, the related entity is a geopoint or a collection of geopoints. Consider the example that below saves a data object with a related geopoint. The geopoint is also persisted in the Geo Service:

curl -H Content-Type:"application/json" \  
-X POST \  
-d '{"name":"Bob", "age":33, "phoneNumber":"212-555-1212", "coordinates":  {"___class":"GeoPoint", "latitude":12.21, "longitude":32.0, "categories":["City"]}}' \  
-v "" 

Notice coordinates property of the data object being saved. It contains a JSON object with a special "___class":"GeoPoint" property. The presence of that property identifies the coordinates object as a GeoPoint. Additionally, the latitude and longitude properties in the GeoPoint object are required. The categories property is optional. If present, it must be an array of strings, where each string identifies the category the geo point belongs to. If the categories property is not present, the geo point will be saved in the default category.

The example above saves a one-to-one relationship between the data object and a geo point. To make it a one-to-many relationship change the value of the coordinates property to an array:

curl -H Content-Type:"application/json" \  
-X POST \  
-d '{"name":"Bob", "age":33, "phoneNumber":"212-555-1212", "coordinates": \  
[{"___class":"GeoPoint", "latitude":48.85, "longitude":2.35, "categories":["City"],"metadata":{"description":{ \  
"___class":"City", "name":"Paris", "population":2249975, "country":"France", "website":""}}}, \  
{"___class":"GeoPoint","latitude":40.40, "longitude":3.68, "categories":["City"], "metadata":{"description":{ \  
"___class":"City", "name":"Paris", "population":3236344, "country":"Spain","website":""}}}]}' \  
-v "" 

After you run the code, you will see the following data object and geopoints created in the application:

Data object: