JayData.org

Geography and geometry with JayData

Author: Gábor Dolla April 30th, 2013

, ,


Geography is an important aspect, just think of the many online apps that use various map services such as Google Maps, OSM, Bing Maps, Nokia Here, etc. OData V3 also has support for Geography and Geometry data types. In JayData 1.3 we also started to support these data types not only in oData but in local providers, too. Our data types follow oData v3 definitions and GeoJSON.

Geography types

Geography data represents points and shapes on planet Earth. Each point is represented by longitude and latitude in decimal degrees. The following types are supported:

$data.GeographyPoint

This type represents a single geography point. The constructor accepts the longitude and langitude in various formats:

You can access the coordinates using longitude and latitude properties:

$data.GeographyMultiPoint

This type represents two or more points as in GeoJSON multipoint specification. The points must be specified in an array, longitude first, latitude next:

$data.GeographyLineString

This type represents a line with two or more points as in GeoJSON line string specification. The points must be represented as an array, longitude first, latitude next:

$data.GeographyMultiLineString

This type represents two or more lines as in GeoJSON multi line string specification. The lines must be represented as an array.

$data.GeographyPolygon

This type represents a polygon as in GeoJSON polygon specification.

We have a shortcut for rectangles as they’re frequently needed. You can easily created a rectangle shaped polygon using one of the two the special constructors:

When specifying a point, any constructor of $data.GeographyPoint can be used or you can place an instance of $data.GeographyPoint there, too.

$data.GeographyMultiPolygon

This type represents multiple polygons as in GeoJSON multi polygon specification.

$data.GeographyCollection

This type represents a collection of geometry objects as in GeoJSON geometry collection specification.

Warning: all data inside arrays are just numbers, currently you can not use other data types there.

Geometry types

Geometry is similar to geography but geometry data represents points and shapes in a Cartesian coordinate system so instead of longitude and latitude the points have x and y coordinates.

All Geography types exists for Geometry, just replace Geography with Geometry (like $data.GeometryPoint) and replace latitude and longitude with x and y.

Working with geo types

Store / retrieve

Geo types can be used just as any other primitive types so they can be stored and retrieved over oData and local providers. You can find several examples here: http://jaydata.org/examples/?tags=Geo.

Here is a small snippet on how to put markers onto a Leaflet map:

map-leaflet

Filters

Geo data can be used in a filter with restrictions. From the standard operators only equals and not equals can be used. There are two special filters for geo search: distance and intersects.

Warning: currently geo search can only used with oData and only if the oData backend supports these functions. As of today (30th April, 2013) only our oData backends support these filters out of the box: JayStorm 1.1 (free and non-free), JayServer + MongoDB Pro Provider and JayServer Pro + MongoDB Pro Provider. With all mentioned oData backends it’s crusial to define geography index! Only one geo search can be included in a filter. The geo index on the server side must match with the filter fields.

Distance

With this functions you can find points within a circle, the center of the circle and the radius are parameters.

Here a small example for distance: http://jaydata.org/examples/Geo/GeoSearch

This example uses leaflet.js. When you click on the map our callback function is called and the incoming parameter has a parameter ‘latlng’ which is the coordinates of the point where you’ve clicked. We pass this value to the filter a ‘p’. The filter uses radian to measure distance, so to find all points that are not farther from ‘p’ more than 500 meters we have to calculate 500 meters into radians. 6371000 is the mean radius of the Earth in meters.

With distance you can only search for points where the distance is less then the given radian.

Intersects

With this functions you can find points within a polygon. This is an example with leaflet.js, select points that are visible:

 


, ,