![\"Geospatial](\"https:\/\/res.cloudinary.com\/code-mill-technologies-inc\/image\/upload\/v1521222910\/app_fgnjjf.gif\")
<\/p>\n\t\t\t\tAzure CosmosDB is a multi-model, globally distributed database, as well as a geospatial calculation powerhouse. It can calculate the distance between two points, determine whether a road runs through a city, and identify if a body of water is wholly contained within a state. In this article, you’ll learn how to unleash the potential of Azure CosmosDB so your apps can handle geographic data on a cosmic scale!<\/p>\n
We’ll walk through the process of adding geospatial calculations to an app that will be able to determine features contained within a boundary, what features intersect with each other, and the distance features are from a single point.<\/p>\n
For this post, Madison Wisconsin USA will be the location data is pulled from.<\/p>\n
<\/p>\n
Spatial data describes the position and shape of objects in space. In most apps, we’re interested in locations on Earth: the location of a landmark, the route of a road, or the boundaries of a city. This geographical, or geospatial, data can be described by using three different types of data: Points<\/strong>, Line Strings<\/strong>, and Polygons<\/strong>.<\/p>\n There are three operations you can perform with this geospatial data.\u00a0Distance<\/strong>, Intersects<\/strong>, and Within<\/strong>.<\/p>\n Now that you know what geospatial data is and the operations you can perform with it, let’s see how to work with it in your Xamarin apps!<\/p>\n If you don’t already know how to work with CosmosDB, check out this excellent documentation<\/a> on working with CosmosDB and Xamarin apps.<\/em><\/p>\n Xamarin apps accesses CosmosDB with the\u00a0Microsoft.Azure.DocumentDB NuGet<\/a>\u00a0package (the DocumentDB refers to one of the underlying databases that CosmosDB supports). The NuGet package contains several classes that model the geospatial types mentioned above, and the classes contain helper methods which perform the various operations on geospatial data.<\/p>\n The app we’re building works with the following geospatial features:<\/p>\n There are polygons to represent the entire state of Wisconsin, the city of Madison, the city of Milwaukee, and the city of Chicago. Line strings represent major highways. Finally, there’s a single point to represent the location of an annual Cheese Curd Festival (because it’s Wisconsin and they love cheese! \ud83e\uddc0). Each of these locations will be referred to as features. You can view this in CosmosDB by clicking here<\/a>.<\/p>\n By picking a feature, and then a spatial operation, you’re able to determine which highways and cities intersect each other, or which cities contain which highways, or even how far a city is away from the Cheese Festival (very important)! There are many combinations of what one can do.<\/p>\n The first thing the app needs to do is select a feature. It does so with the following code:<\/p>\n This is a common CosmosDB query for finding a document and follows the documentation<\/a> closely. From here on out, the returned document will be used in the other operations as the feature to compare against.<\/p>\n Let’s start with the most important question, the distance of the features to the Cheese Curd Festival!<\/p>\n That’s it! The base class for all geospatial objects,\u00a0 Pull the results from the DocumentQuery<\/span>\u00a0exactly as you normally would.<\/p>\n The following code finds everything in the database that crosses paths or intersects with the passed-in\u00a0 That’s all there is to it! This will find everything in the database that intersects with the passed in feature.<\/p>\n By now, you may be able to guess how this is done. There’s a\u00a0 The best part? These queries return lightning fast, even though there are many points, line strings, and polygons being queried!<\/p>\n You can view the full code for this sample here<\/a>. There’s also ample documentation for spatial operation in Azure CosmosDB on docs.microsoft.com<\/a>, and a recently completed app that makes use of CosmosDB’s spatial features plus a number of other Azure offerings here<\/a>.<\/p>\n The best thing to do, though, is trying it for yourself! Create a free Azure account<\/a>\u00a0(with enough credit to use CosmosDB for a year!), set up a CosmosDB instance<\/a>, and start creating your own spatially aware database today!<\/p>\n\n
\n
Working With Geospatial Data<\/h2>\n
![\"Geospatial](\"https:\/\/res.cloudinary.com\/code-mill-technologies-inc\/image\/upload\/c_scale,h_600\/v1521218867\/Screen_Shot_2018-03-16_at_11.36.26_AM_se7mjf.png\")
<\/p>\nSelecting a Feature<\/h3>\n
\/\/ collectionURI is a URI pointing to the CosmosDB collection\nvar featureQuery = client.CreateDocumentQuery<Feature>(collectionUri)\n .Where(f => f.LocationName == featureName)\n .Take(1)\n .AsDocumentQuery();<\/pre>\n
Finding the Distance<\/h3>\n
\/\/ cheeseFestival is a Point\nvar distanceQuery = client.CreateDocumentQuery<Feature>(collectionUri)\n .Where(f => f.Id == feature.Id) \/\/ feature is what you want to find out how far away it is\n .Select(f => cheeseFestival.Distance(f.Location)) \/\/ Location is a Geometry type\n .AsDocumentQuery();<\/pre>\n
Microsoft.Azure.Documents.Spatial.Geometry<\/code>\u00a0contains a\u00a0Distance<\/code>\u00a0function which will tell CosmosDB to figure out the distances between all the various geometries and the point\/return that as a\u00a0double<\/code>.<\/p>\nFinding Intersections<\/h3>\n
feature<\/code>:<\/p>\nvar intersectingQuery = client.CreateDocumentQuery<Feature>(collectionUri)\n .Where(f => feature.Id != f.Id) \/\/ Ignore passed in\n .Where(f => feature.Location.Intersects(f.Location)) \n .AsDocumentQuery();<\/pre>\n
Finding Features Contained Within<\/h3>\n
Within<\/code>\u00a0function that determines which objects are wholly contained within another. The code looks like this:<\/p>\nvar withinQuery = client.CreateDocumentQuery<Feature>(collectionUri)\n .Where(f => feature.Id != f.Id) \/\/ Ignore passed in\n .Where(f => f.Location.Within(feature.Location)) \n .AsDocumentQuery();<\/pre>\n
Next Steps<\/h2>\n