Geospatial - Node.js SDK

GeoPoint

A GeoPoint defines a specific location on the Earth's surface. All of the geospatial data types use GeoPoints to define their location.

GeoPoint can be one of three types:

• An object with:

  • latitude: a number value

  • longitude: a number value

  • altitude: an optional number value

• CanonicalGeoPoint: an interface that satisfies the GeoJSON specifications for a point

• GeoPosition: an array with longitude, latitude, and an optional altitude

A GeoPoint is used only as a building block of the other shapes: GeoCircle, GeoBox, and GeoPolygon. These shapes, and the GeoPoint type, are used in queries, not for persistance.

To save geospatial data to realm, refer to Persist Geospatial Data.

GeoCircle

A GeoCircle defines a circle on the Earth's surface. You define a GeoCircle by providing:

• A GeoPoint for the center of the circle

• A number for the distance (radius) of the circle

The radius distance uses radians as the unit of measure. The SDK provides the methods kmToRadians and miToRadians to convert kilometers or miles to radians.

The following code shows two examples of creating a circle:

click to enlarge

GeoBox

A GeoBox defines a rectangle on the Earth's surface. You define the rectangle by specifying the bottom left (southwest) corner and the top right (northeast) corner. A GeoBox behaves in the same way as the corresponding GeoPolygon.

The following example creates 2 boxes:

click to enlarge

GeoPolygon

A GeoPolygon defines a polygon on the Earth's surface. Because a polygon is a closed shape, you must provide a minimum of 4 points: 3 points to define the polygon's shape, and a fourth to close the shape.

You can also exclude areas within a polygon by defining one or more "holes". A hole is another polygon whose bounds fit completely within the outer polygon. The following example creates 3 polygons: one is a basic polygon with 5 points, one is the same polygon with a single hole, and the third is the same polygon with two holes:

click to enlarge

Create a GeoJSON-Compatible Class

To create a class that conforms to the GeoJSON spec, you:

1. Create an embedded realm object. For more information about embedded objects, refer to Embedded Objects - Node.js SDK.

2. At a minimum, add the two fields required by the GeoJSON spec:

   • A field of type double[] that maps to a "coordinates" (case sensitive) property in the realm schema.

   • A field of type string that maps to a "type" property. The value of this field must be "Point".

To simplify geodata persistance, you can define a model that implements CanonicalGeoPoint, which already has the correct shape. The following example shows an embedded class named MyGeoPoint that is used to persist geospatial data:

Use the Embedded Class

You then use the custom MyGeoPoint class in your realm model, as shown in the following example:

You add instances of your class to the realm just like any other Realm model. However, in this example, because the MyGeoPoint class does not extend Realm.Object, we must specify MyGeoPoint.schema when opening the realm:

The following image shows the results of creating these two company objects.

click to enlarge