Skip to content

Commit 4ed004e

Browse files
seesharprunseesharprun
committed
Update geospatial landing page
1 parent 7de6eaa commit 4ed004e

File tree

1 file changed

+79
-86
lines changed

1 file changed

+79
-86
lines changed

‎articles/cosmos-db/nosql/query/geospatial.md‎

Lines changed: 79 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -16,108 +16,100 @@ ms.custom: query-reference
1616

1717
[!INCLUDE[NoSQL](../../includes/appliesto-nosql.md)]
1818

19-
This article is an introduction to the geospatial functionality in Azure Cosmos DB. After reading our documentation on geospatial indexing, you'll be able to answer the following questions:
19+
Azure Cosmos DB for NoSQL has built-in geospatial functionality to represent geometric shapes or actual locations/polygons on a map.
2020

21-
- How do I store spatial data in Azure Cosmos DB?
22-
- How can I query spatial data in Azure Cosmos DB in SQL and LINQ?
23-
- How do I enable or disable spatial indexing in Azure Cosmos DB?
21+
Geospatial data often involves proximity queries. For example, the question "find all retail locations near my current location" is answered using a proximity query over multiple geospatial data object.
2422

25-
## Spatial Data Use Cases
23+
Common geospatial use cases include, but aren't limited to:
2624

27-
Geospatial data often involve proximity queries, for example, "find all coffee shops near my current location". Common use cases are:
28-
29-
- Geolocation Analytics, driving specific located marketing initiatives.
30-
- Location based personalization, for multiple industries like Retail and Healthcare.
31-
- Logistics enhancement, for transport optimization.
32-
- Risk Analysis, especially for insurance and finance companies.
33-
- Situational awareness, for alerts and notifications.
25+
- **Geolocation analytics**, driving specific location-based marketing initiatives.
26+
- **Location-based personalization**, for industries like retail and healthcare to improve user experience.
27+
- **Logistics enhancement**, for industries like transportation where optimization is critical.
28+
- **Risk Analysis**, for industries like insurance and finance to supplement other metadata.
29+
- **Situational awareness***, for proxmiity-based alerts and notifications.
3430

3531
## Introduction to spatial data
3632

37-
Spatial data describes the position and shape of objects in space. In most applications, these correspond to objects on the earth and geospatial data. Spatial data can be used to represent the location of a person, a place of interest, or the boundary of a city, or a lake.
33+
Spatial data describes the position and shape of objects in space. In most applications, these points and shapes correspond to objects on the earth and geospatial data. Spatial data can be used to represent the location of a person, a place of interest, or the boundary of a city, or a lake.
3834

39-
Azure Cosmos DB's API for NoSQL supports two spatial data types: the **geometry** data type and the **geography** data type.
35+
Azure Cosmos DB for NoSQL supports two spatial data types: the **geometry** data type and the **geography** data type.
4036

41-
- The **geometry** type represents data in a Euclidean (flat) coordinate system
42-
- The **geography** type represents data in a round-earth coordinate system.
37+
- The **geometry** type represents data in a Euclidean (flat) coordinate system. This type is useful for common geometric tasks, like measuring lines, intersecting polygons, and measuring distance between points.
38+
- The **geography** type represents data in a round-earth coordinate system. This type is useful for common geographical tasks, like determining if a location is within specific bounds and measuring distance between locations.
4339

4440
## Supported data types
4541

46-
Azure Cosmos DB supports indexing and querying of geospatial point data that's represented using the [GeoJSON specification](https://tools.ietf.org/html/rfc7946). GeoJSON data structures are always valid JSON objects, so they can be stored and queried using Azure Cosmos DB without any specialized tools or libraries.
42+
Azure Cosmos DB for NoSQL supports indexing and querying of geospatial point data that's represented using the [GeoJSON specification](https://tools.ietf.org/html/rfc7946). GeoJSON data structures are always valid JSON objects, so they can be stored and queried using Azure Cosmos DB without any specialized tools or libraries.
4743

4844
Azure Cosmos DB supports the following spatial data types:
4945

50-
- Point
51-
- LineString
52-
- Polygon
53-
- MultiPolygon
54-
55-
> [!TIP]
56-
> Currently spatial data in Azure Cosmos DB is not supported by Entity Framework. Please use one of the Azure Cosmos DB SDKs instead.
46+
- **Point**
47+
- **LineString**
48+
- **Polygon**
49+
- **MultiPolygon**
5750

5851
### Points
5952

60-
A **Point** denotes a single position in space. In geospatial data, a Point represents the exact location, which could be a street address of a grocery store, a kiosk, an automobile, or a city. A point is represented in GeoJSON (and Azure Cosmos DB) using its coordinate pair or longitude and latitude.
61-
62-
Here's an example JSON for a point:
53+
A **Point** denotes a single position in space. In geospatial data, a Point represents the exact location, which could be a street address of a grocery store, a kiosk, an automobile, or a city. A point is represented in GeoJSON (and Azure Cosmos DB for NOSQL) using its coordinate pair (**longitude** and **latitude**).
6354

64-
**Points in Azure Cosmos DB**
55+
Consider this example GeoJSON point. The longitude is ``-122.12826822304672`` and the latitude is ``47.63980239335718``.
6556

6657
```json
6758
{
68-
"type":"Point",
69-
"coordinates":[ 31.9, -4.8 ]
59+
"type": "Point",
60+
"coordinates": [
61+
-122.12826822304672,
62+
47.63980239335718
63+
]
7064
}
7165
```
7266

73-
Spatial data types can be embedded in an Azure Cosmos DB document as shown in this example of a user profile containing location data:
67+
> [!TIP]
68+
> For the **geography** data type, GeoJSON specification specifies longitude first and latitude second. Like in other mapping applications, longitude and latitude are angles and represented in terms of degrees. Longitude values are measured from the Prime Meridian and are between ``-180`` degrees and ``180.0`` degrees, and latitude values are measured from the equator and are between ``-90.0`` degrees and ``90.0`` degrees.
69+
>
70+
> For the **geometry** data type, GeoJSON specification specifies the horizontal axis first and the vertical axis second.
7471
75-
**Use Profile with Location stored in Azure Cosmos DB**
72+
Spatial data types can be embedded in an item as shown in this example of a facility item that includes the GeoJSON data.
7673

7774
```json
7875
{
79-
"id":"cosmosdb-profile",
80-
"screen_name":"@CosmosDB",
81-
"city":"Redmond",
82-
"topics":[ "global", "distributed" ],
83-
"location":{
84-
"type":"Point",
85-
"coordinates":[ 31.9, -4.8 ]
86-
}
76+
"name": "Headquarters",
77+
"location": {
78+
"type": "Point",
79+
"coordinates": [
80+
-122.12826822304672,
81+
47.63980239335718
82+
]
83+
},
84+
"category": "business-offices"
8785
}
8886
```
8987

90-
### Points in a geometry coordinate system
91-
92-
For the **geometry** data type, GeoJSON specification specifies the horizontal axis first and the vertical axis second.
93-
94-
### Points in a geography coordinate system
95-
96-
For the **geography** data type, GeoJSON specification specifies longitude first and latitude second. Like in other mapping applications, longitude and latitude are angles and represented in terms of degrees. Longitude values are measured from the Prime Meridian and are between -180 degrees and 180.0 degrees, and latitude values are measured from the equator and are between -90.0 degrees and 90.0 degrees.
97-
98-
Azure Cosmos DB interprets coordinates as represented per the WGS-84 reference system. See below for more details about coordinate reference systems.
88+
Azure Cosmos DB for NoSQL interprets coordinates as represented per the WGS-84 reference system. For more information, see [coordinate reference systems](#coordinate-reference-systems).
9989

10090
### LineStrings
10191

10292
**LineStrings** represent a series of two or more points in space and the line segments that connect them. In geospatial data, LineStrings are commonly used to represent highways or rivers.
10393

104-
**LineStrings in GeoJSON**
94+
In this example, a line string is used to represent a line that drawn between two points.
10595

10696
```json
10797
{
108-
"type":"LineString",
109-
"coordinates":[
110-
[ 31.8, -5 ],
111-
[ 31.8, -4.7 ]
112-
]
98+
"type": "LineString",
99+
"coordinates": [
100+
[ 31.8, -5 ],
101+
[ 31.8, -4.7 ]
102+
]
113103
}
114104
```
115105

116106
### Polygons
117107

118-
A **Polygon** is a boundary of connected points that forms a closed LineString. Polygons are commonly used to represent natural formations like lakes or political jurisdictions like cities and states. Here's an example of a Polygon in Azure Cosmos DB:
108+
A **Polygon** is a boundary of connected points that forms a closed LineString. Polygons are commonly used to represent natural formations like lakes or political jurisdictions like cities and states.
119109

120-
**Polygons in GeoJSON**
110+
Points within a Polygon must be specified in counter-clockwise order. A Polygon specified in clockwise order represents the inverse of the region within it.
111+
112+
In this example, a polygon is created by connecting multiple points.
121113

122114
```json
123115
{
@@ -132,67 +124,64 @@ A **Polygon** is a boundary of connected points that forms a closed LineString.
132124
}
133125
```
134126

135-
> [!NOTE]
136-
> The GeoJSON specification requires that for valid Polygons, the last coordinate pair provided should be the same as the first, to create a closed shape.
137-
>
138-
> Points within a Polygon must be specified in counter-clockwise order. A Polygon specified in clockwise order represents the inverse of the region within it.
139-
>
140-
>
127+
> [!TIP]
128+
> The GeoJSON specification requires that for valid Polygons, the last coordinate pair provided should be the same as the first, to create a closed shape.
141129
142130
### MultiPolygons
143131

144132
A **MultiPolygon** is an array of zero or more Polygons. **MultiPolygons** can't overlap sides or have any common area. They may touch at one or more points.
145133

146-
**MultiPolygons in GeoJSON**
134+
Here's an example of a MultiPolygon.
147135

148136
```json
149137
{
150138
"type":"MultiPolygon",
151139
"coordinates":[[[
152-
[52.0, 12.0],
153-
[53.0, 12.0],
154-
[53.0, 13.0],
155-
[52.0, 13.0],
156-
[52.0, 12.0]
140+
[52.0, 12.0],
141+
[53.0, 12.0],
142+
[53.0, 13.0],
143+
[52.0, 13.0],
144+
[52.0, 12.0]
157145
]],
158146
[[
159-
[50.0, 0.0],
160-
[51.0, 0.0],
161-
[51.0, 5.0],
162-
[50.0, 5.0],
163-
[50.0, 0.0]
147+
[50.0, 0.0],
148+
[51.0, 0.0],
149+
[51.0, 5.0],
150+
[50.0, 5.0],
151+
[50.0, 0.0]
164152
]]]
165153
}
166154
```
167155

168156
## Coordinate reference systems
169157

170-
Since the shape of the earth is irregular, coordinates of geography geospatial data are represented in many coordinate reference systems (CRS), each with their own frames of reference and units of measurement. For example, the "National Grid of Britain" is a reference system is accurate for the United Kingdom, but not outside it.
158+
Since the shape of the earth is irregular, coordinates of geography geospatial data are represented in many coordinate reference systems (CRS). Each CRS has their own frames of reference and units of measurement. For example, the "National Grid of Britain" is a reference system is accurate for the United Kingdom, but not outside it.
171159

172-
The most popular CRS in use today is the World Geodetic System [WGS-84](https://earth-info.nga.mil/GandG/update/index.php). GPS devices, and many mapping services including Google Maps and Bing Maps APIs use WGS-84. Azure Cosmos DB supports indexing and querying of geography geospatial data using the WGS-84 CRS only.
160+
The most popular CRS in use today is the World Geodetic System [WGS-84](https://earth-info.nga.mil/GandG/update/index.php). GPS devices, and many mapping services including Google Maps and Bing Maps APIs use WGS-84. Azure Cosmos DB for NoSQL supports indexing and querying of geography geospatial data using the WGS-84 CRS only.
173161

174-
## Creating documents with spatial data
175-
When you create documents that contain GeoJSON values, they're automatically indexed with a spatial index in accordance to the indexing policy of the container. If you're working with an Azure Cosmos DB SDK in a dynamically typed language like Python or Node.js, you must create valid GeoJSON.
162+
## Creating items with spatial data
176163

177-
**Create Document with Geospatial data in Node.js**
164+
When you create items that contain GeoJSON values, they're automatically indexed with a spatial index. This default indexing occurs in accordance to the indexing policy of the container. The default indexing policy, if not specified, will accurately index GeoJSON data. If you're working with an SDK in a dynamically typed language like Python or Node.js, you must create valid GeoJSON.
165+
166+
### [JavaScript](#tab/javascript)
178167

179168
```javascript
180-
var userProfileDocument = {
169+
var userProfileitem = {
181170
"id":"cosmosdb",
182171
"location":{
183172
"type":"Point",
184173
"coordinates":[ -122.12, 47.66 ]
185174
}
186175
};
187176

188-
client.createDocument(`dbs/${databaseName}/colls/${collectionName}`, userProfileDocument, (err, created) => {
177+
client.createitem(`dbs/${databaseName}/colls/${collectionName}`, userProfileitem, (err, created) => {
189178
// additional code within the callback
190179
});
191180
```
192181

193-
If you're working with the API for NoSQLs, you can use the `Point`, `LineString`, `Polygon`, and `MultiPolygon` classes within the `Microsoft.Azure.Cosmos.Spatial` namespace to embed location information within your application objects. These classes help simplify the serialization and deserialization of spatial data into GeoJSON.
182+
### [C#](#tab/csharp)
194183

195-
**Create Document with Geospatial data in .NET**
184+
If you're working with the API for NoSQLs, you can use the `Point`, `LineString`, `Polygon`, and `MultiPolygon` classes within the `Microsoft.Azure.Cosmos.Spatial` namespace to embed location information within your application objects. These classes help simplify the serialization and deserialization of spatial data into GeoJSON.
196185

197186
```csharp
198187
using Microsoft.Azure.Cosmos.Spatial;
@@ -208,14 +197,18 @@ public class UserProfile
208197
// More properties
209198
}
210199

211-
await container.CreateItemAsync( new UserProfile
200+
await container.CreateItemAsync(
201+
new UserProfile
212202
{
213203
id = "cosmosdb",
214204
Location = new Point (-122.12, 47.66)
215-
});
205+
}
206+
);
216207
```
217208

218-
If you don't have the latitude and longitude information, but have the physical addresses or location name like city or country/region, you can look up the actual coordinates by using a geocoding service like Bing Maps REST Services. Learn more about Bing Maps geocoding [here](/bingmaps/rest-services/).
209+
---
210+
211+
If you don't have the latitude and longitude information, but have the physical addresses or location name, look up the actual coordinates using an online service. Services like Bing Maps can assist with finding the actual geography data from a known location name. For more information about Bing Maps geocoding, see [Bing Maps REST Services](/bingmaps/rest-services/).
219212

220213
## Next steps
221214

0 commit comments

Comments
 (0)