Geospatial - Flutter 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.

A GeoPoint is an object with two required properties:

• lat: a double value

• lon: a double value

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

To save geospatial data to the database, 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 GeoDistance for the distance (radius) of the circle

The radius distance uses radians as the unit of measure, implemented as a double in the SDK. The SDK provides convenience methods to create a GeoDistance from other units of measure:

• GeoDistance.fromDegrees()

• GeoDistance.fromKilometers()

• GeoDistance.fromMeters()

• GeoDistance.fromMiles()

The following code shows two examples of creating a circle:

final smallCircle =
    GeoCircle(GeoPoint(lon: -121.9, lat: 47.3), 0.25.degrees);
final largeCircleCenter = GeoPoint(lon: -122.6, lat: 47.8);
// The SDK provides convenience methods to convert measurements to radians.
final radiusFromKm = GeoDistance.fromKilometers(44.4);
final largeCircle = GeoCircle(largeCircleCenter, radiusFromKm);

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.

The following example creates 2 boxes:

final largeBox = GeoBox(
    GeoPoint(lon: -122.7, lat: 47.3), GeoPoint(lon: -122.1, lat: 48.1));
final smallBoxSouthWest = GeoPoint(lon: -122.4, lat: 47.5);
final smallBoxNorthEast = GeoPoint(lon: -121.8, lat: 47.9);
final smallBox = GeoBox(smallBoxSouthWest, smallBoxNorthEast);

click to enlarge

Create a GeoJSON-Compatible Class

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

1. Create an embedded object. For more information about embedded objects, refer to Embedded Objects.

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 schema.

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

The following example shows an embedded class named MyGeoPoint that is used to persist geospatial data:

// To store geospatial data, create an embedded object with this structure.
// Name it whatever is most convenient for your application.
@RealmModel(ObjectType.embeddedObject)
class _MyGeoPoint {
  // These two properties are required to persist geo data.
  final String type = 'Point';
  final List<double> coordinates = const [];
  // You can optionally implement convenience methods to simplify
  // creating and working with geospatial data.
  double get lon => coordinates[0];
  set lon(double value) => coordinates[0] = value;
  double get lat => coordinates[1];
  set lat(double value) => coordinates[1] = value;
  GeoPoint toGeoPoint() => GeoPoint(lon: lon, lat: lat);
}

Use the Embedded Class

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

// Use the GeoJSON-compatible class as a property in your model.
@RealmModel()
class _Company {
  @PrimaryKey()
  late ObjectId id;
  _MyGeoPoint? location;
}

You add instances of your class to the database just like any other model.

final realm =
    Realm(Configuration.local([MyGeoPoint.schema, Company.schema]));
realm.write(() {
  realm.addAll([
    Company(
      firstCompanyID,
      location: MyGeoPoint(coordinates: [-122.35, 47.68]),
    ),
    Company(
      secondCompanyID,
      location: MyGeoPoint(coordinates: [-121.85, 47.9]),
    )
  ]);
});

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

click to enlarge