Skip to content

Commit c9a99c2

Browse files
tamarakhadertamarakhader
authored
Merge pull request #214548 from stevemunk/SM-Building-GeoJson-Dataset
New article how-to create dataset using GeoJSON
2 parents 641c7d4 + 2872ee2 commit c9a99c2

File tree

3 files changed

+194
-0
lines changed

3 files changed

+194
-0
lines changed

‎articles/azure-maps/how-to-dataset-geojson.md

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
---
2+
title: How to create a dataset using a GeoJson package
3+
description: Learn how to create a dataset using a GeoJson package embedding the module's JavaScript libraries.
4+
author: stevemunk
5+
ms.author: v-munksteve
6+
ms.date: 10/31/2021
7+
ms.topic: how-to
8+
ms.service: azure-maps
9+
services: azure-maps
10+
---
11+
12+
# Create a dataset using a GeoJson package (Preview)
13+
14+
Azure Maps Creator enables users to import their indoor map data in GeoJSON format with [Facility Ontology 2.0][Facility Ontology], which can then be used to create a [dataset][dataset-concept].
15+
16+
> [!NOTE]
17+
> This article explains how to create a dataset from a GeoJSON package. For information on additional steps required to complete an indoor map, see [Next steps](#next-steps).
18+
19+
## Prerequisites
20+
21+
- Basic understanding of [Creator for indoor maps](creator-indoor-maps.md).
22+
- Basic understanding of [Facility Ontology 2.0][Facility Ontology].
23+
- [Azure Maps account][Azure Maps account].
24+
- [Azure Maps Creator resource][Creator resource].
25+
- [Subscription key][Subscription key].
26+
- Zip package containing all required GeoJSON files. If you don't have GeoJSON
27+
files, you can download the [Contoso building sample][Contoso building sample].
28+
29+
>[!IMPORTANT]
30+
>
31+
> - This article uses the `us.atlas.microsoft.com` geographical URL. If your Creator service wasn't created in the United States, you must use a different geographical URL. For more information, see [Access to Creator Services](how-to-manage-creator.md#access-to-creator-services).
32+
> - In the URL examples in this article you will need to replace `{Azure-Maps-Primary-Subscription-key}` with your primary subscription key.
33+
34+
## Create dataset using the GeoJSON package
35+
36+
For more information on the GeoJSON package, see the [Geojson zip package requirements](#geojson-zip-package-requirements) section.
37+
38+
### Upload the GeoJSON package
39+
40+
Use the [Data Upload API](/rest/api/maps/data-v2/upload) to upload the Drawing package to Azure Maps Creator account.
41+
42+
The Data Upload API is a long running transaction that implements the pattern defined in [Creator Long-Running Operation API V2](creator-long-running-operation-v2.md).
43+
44+
To upload the GeoJSON package:
45+
46+
1. Execute the following HTTP POST request that uses the [Data Upload API](/rest/api/maps/data-v2/upload):
47+
48+
```http
49+
https://us.atlas.microsoft.com/mapData?api-version=2.0&dataFormat=zip&subscription-key={Your-Azure-Maps-Primary-Subscription-key}
50+
```
51+
52+
1. Set `Content-Type` in the **Header** to `application/zip`.
53+
54+
1. Copy the value of the `Operation-Location` key in the response header. The `Operation-Location` key is also known as the `status URL` and is required to check the status of the upload, which is explained in the next section.
55+
56+
### Check the GeoJSON package upload status
57+
58+
To check the status of the GeoJSON package and retrieve its unique identifier (`udid`):
59+
60+
1. Execute the following HTTP GET request that uses the status URL you copied as the last step in the previous section of this article. The request should look like the following URL:
61+
62+
```http
63+
https://us.atlas.microsoft.com/mapData/operations/{operationId}?api-version=2.0&subscription-key={Your-Azure-Maps-Primary-Subscription-key}
64+
```
65+
66+
1. Copy the value of the `Resource-Location` key in the response header, which is the `resource location URL`. The `resource location URL` contains the unique identifier (`udid`) of the GeoJSON package resource.
67+
68+
### Create a dataset
69+
<!-->
70+
A dataset is a collection of map features, such as buildings, levels, and rooms. To create a dataset from your GeoJSON, use the new [Dataset Create API][Dataset Create 2022-09-01-preview]. The Dataset Create API takes the `udid` you got in the previous section and returns the `datasetId` of the new dataset.
71+
-->
72+
A dataset is a collection of map features, such as buildings, levels, and rooms. To create a dataset from your GeoJSON, use the new create dataset API. The create dataset API takes the `udid` you got in the previous section and returns the `datasetId` of the new dataset.
73+
74+
> [!IMPORTANT]
75+
> This is different from the [previous version][Dataset Create] in that it doesn't require a `conversionId` from a converted Drawing package.
76+
77+
To create a dataset:
78+
79+
1. Enter the following URL to the dataset service. The request should look like the following URL (replace {udid} with the `udid` obtained in [Check the GeoJSON package upload status](#check-the-geojson-package-upload-status) section):
80+
81+
<!--1. Enter the following URL to the [Dataset service][Dataset Create 2022-09-01-preview]. The request should look like the following URL (replace {udid} with the `udid` obtained in [Check the GeoJSON package upload status](#check-the-geojson-package-upload-status) section):-->
82+
83+
```http
84+
https://us.atlas.microsoft.com/datasets?api-version=2022-09-01-preview&udid={udid}&subscription-key={Your-Azure-Maps-Primary-Subscription-key}
85+
```
86+
87+
1. Copy the value of the `Operation-Location` key in the response header. The `Operation-Location` key is also known as the `status URL` and is required to check the status of the dataset creation process and to get the `datasetId`, which is required to create a tileset.
88+
89+
### Check the dataset creation status
90+
91+
To check the status of the dataset creation process and retrieve the `datasetId`:
92+
93+
1. Enter the status URL you copied in [Create a dataset](#create-a-dataset). The request should look like the following URL:
94+
95+
```http
96+
https://us.atlas.microsoft.com/datasets/operations/{operationId}?api-version=2022-09-01-preview&subscription-key={Your-Azure-Maps-Primary-Subscription-key}
97+
```
98+
99+
1. In the Header of the HTTP response, copy the value of the unique identifier contained in the `Resource-Location` key.
100+
101+
> https://us.atlas.microsoft.com/datasets/**c9c15957-646c-13f2-611a-1ea7adc75174**?api-version=2022-09-01-preview
102+
103+
See [Next steps](#next-steps) for links to articles to help you complete your indoor map.
104+
105+
## Add data to an existing dataset
106+
107+
<!--
108+
Data can be added to an existing dataset by providing the `datasetId` parameter to the [dataset create API][Dataset Create 2022-09-01-preview] along with the unique identifier of the data you wish to add. The unique identifier can be either a `udid` or `conversionId`. This creates a new dataset consisting of the data (facilities) from both the existing dataset and the new data being imported. Once the new dataset has been created successfully, the old dataset can be deleted.
109+
-->
110+
111+
Data can be added to an existing dataset by providing the `datasetId` parameter to the create dataset API along with the unique identifier of the data you wish to add. The unique identifier can be either a `udid` or `conversionId`. This creates a new dataset consisting of the data (facilities) from both the existing dataset and the new data being imported. Once the new dataset has been created successfully, the old dataset can be deleted.
112+
113+
One thing to consider when adding to an existing dataset is how the feature IDs are created. If a dataset is created from a converted drawing package, the feature IDs are generated automatically. When a dataset is created from a GeoJSON package, feature IDs must be provided in the GeoJSON file. When appending to an existing dataset, the original dataset drives the way feature IDs are created. If the original dataset was created using a `udid`, it uses the IDs from the GeoJSON, and will continue to do so with all GeoJSON packages appended to that dataset in the future. If the dataset was created using a `conversionId`, IDs will be internally generated, and will continue to be internally generated with all GeoJSON packages appended to that dataset in the future.
114+
115+
### Add to dataset created from a GeoJSON source
116+
117+
If your original dataset was created from a GoeJSON source and you wish to add another facility created from a drawing package, you can append it to your existing dataset by referencing its `conversionId`, as demonstrated by this HTTP POST request:
118+
119+
```http
120+
https://us.atlas.microsoft.com/datasets?api-version=2022-09-01-preview&conversionId={conversionId}&outputOntology=facility-2.0&datasetId={datasetId}
121+
```
122+
123+
| Identifier | Description |
124+
|--------------|-------------------------------------------------------------------|
125+
| conversionId | The ID returned when converting your drawing package. For more information, see [Convert a Drawing package][conversion]. |
126+
| datasetId | The dataset ID returned when creating the original dataset from a GeoJSON package). |
127+
128+
<!--For more information, see [][].-->
129+
130+
## Geojson zip package requirements
131+
132+
The GeoJSON zip package consists of one or more [RFC 7946][RFC 7946] compliant GeoJSON files, one for each feature class, all in the root directory (subdirectories aren't supported), compressed with standard Zip compression and named using the `.ZIP` extension.
133+
134+
Each feature class file must match its definition in the [Facility ontology 2.0][Facility ontology] and each feature must have a globally unique identifier.
135+
136+
Feature IDs can only contain alpha-numeric (a-z, A-Z, 0-9), hyphen (-), dot (.) and underscore (_) characters.
137+
138+
> [!TIP]
139+
> If you want to be certain you have a globally unique identifier (GUID), consider creating it by running a GUID generating tool such as the Guidgen.exe command line program (Available with [Visual Studio][Visual Studio]). Guidgen.exe never produces the same number twice, no matter how many times it is run or how many different machines it runs on.
140+
141+
### Facility ontology 2.0 validations in the Dataset
142+
143+
[Facility ontology][Facility ontology] defines how Azure Maps Creator internally stores facility data, divided into feature classes, in a Creator dataset. When importing a GeoJSON package, anytime a feature is added or modified, a series of validations run. This includes referential integrity checks as well as geometry and attribute validations. These validations are described in more detail below.
144+
145+
- The maximum number of features that can be imported into a dataset at a time is 150,000.
146+
- The facility area can be between 4 and 4,000 Sq Km.
147+
- The top level element is [facility][facility], which defines each building in the file *facility.geojson*.
148+
- Each facility has one or more levels, which are defined in the file *levels.goejson*.
149+
- Each level must be inside the facility.
150+
- Each [level][level] contain [units][unit], [structures][structure], [verticalPenetrations][verticalPenetration] and [openings][opening]. All of the items defined in the level must be fully contained within the Level geometry.
151+
- `unit` can consist of an array of items such as hallways, offices and courtyards, which are defined by [area][areaElement], [line][lineElement] or [point][pointElement] elements. Units are defined in the file *unit.goejson*.
152+
- All `unit` elements must be fully contained within their level and intersect with their children.
153+
- `structure` defines physical, non-overlapping areas that can't be navigated through, such as a wall. Structures are defined in the file *structure.goejson*.
154+
- `verticalPenetration` represents a method of navigating vertically between levels, such as stairs and elevators and are defined in the file *verticalPenetration.geojson*.
155+
- verticalPenetrations can't intersect with other verticalPenetrations on the same level.
156+
- `openings` define traversable boundaries between two units, or a `unit` and `verticalPenetration` and are defined in the file *opening.geojson*.
157+
- Openings can't intersect with other openings on the same level.
158+
- Every `opening` must be associated with at least one `verticalPenetration` or `unit`.
159+
160+
## Next steps
161+
162+
> [!div class="nextstepaction"]
163+
> [Create a tileset](tutorial-creator-indoor-maps.md#create-a-tileset)
164+
165+
> [!div class="nextstepaction"]
166+
> [Query datasets with WFS API](tutorial-creator-wfs.md)
167+
168+
> [!div class="nextstepaction"]
169+
> [Create a feature stateset](tutorial-creator-feature-stateset.md)
170+
171+
[unit]: creator-facility-ontology.md?pivots=facility-ontology-v2#unit
172+
[structure]: creator-facility-ontology.md?pivots=facility-ontology-v2#structure
173+
[level]: creator-facility-ontology.md?pivots=facility-ontology-v2#level
174+
[facility]: creator-facility-ontology.md?pivots=facility-ontology-v2#facility
175+
[verticalPenetration]: creator-facility-ontology.md?pivots=facility-ontology-v2#verticalpenetration
176+
[opening]: creator-facility-ontology.md?pivots=facility-ontology-v2#opening
177+
[areaElement]: creator-facility-ontology.md?pivots=facility-ontology-v2#areaelement
178+
[lineElement]: creator-facility-ontology.md?pivots=facility-ontology-v2#lineelement
179+
[pointElement]: creator-facility-ontology.md?pivots=facility-ontology-v2#pointelement
180+
181+
[conversion]: tutorial-creator-indoor-maps.md#convert-a-drawing-package
182+
[Azure Maps account]: quick-demo-map-app.md#create-an-azure-maps-account
183+
[Creator resource]: how-to-manage-creator.md
184+
[Subscription key]: quick-demo-map-app.md#get-the-primary-key-for-your-account
185+
[Facility Ontology]: creator-facility-ontology.md?pivots=facility-ontology-v2
186+
[RFC 7946]: https://www.rfc-editor.org/rfc/rfc7946.html
187+
[dataset-concept]: creator-indoor-maps.md#datasets
188+
<!--[Dataset Create 2022-09-01-preview]: /rest/api/maps/v20220901preview/dataset/create-->
189+
[Visual Studio]: https://visualstudio.microsoft.com/downloads/

‎articles/azure-maps/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -239,6 +239,8 @@ items:
239239
items:
240240
- name: Indoor Maps module
241241
href: how-to-use-indoor-module.md
242+
- name: Create dataset using GeoJson package (Preview)
243+
href: how-to-dataset-geojson.md
242244
- name: Dynamic styling for indoor maps
243245
href: indoor-map-dynamic-styling.md
244246
- name: Custom styling for indoor maps

‎articles/azure-maps/tutorial-creator-indoor-maps.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,9 @@ In the next tutorials in the Creator series you'll learn to:
2828
> * Create a feature stateset that can be used to set the states of features in your dataset.
2929
> * Update the state of a given map feature.
3030
31+
> [!TIP]
32+
> You can also create a dataset from a GeoJSON package. For more information, see [Create a dataset using a GeoJson package (Preview)](how-to-dataset-geojson.md).
33+
3134
## Prerequisites
3235

3336
1. [Make an Azure Maps account](quick-demo-map-app.md#create-an-azure-maps-account).

0 commit comments

Comments
 (0)