Tutorial: Use Creator to create indoor maps

Article
03/08/2023
7 minutes to read

This tutorial describes how to create indoor maps for use in Microsoft Azure Maps. In this tutorial, you'll learn how to:

Upload your indoor map drawing package.
Convert your drawing package into map data.
Create a dataset from your map data.
Create a tileset from the data in your dataset.
Get the default map configuration ID from your tileset.

Tip

You can also create a dataset from a GeoJSON package. For more information, see Create a dataset using a GeoJson package (Preview).

Prerequisites

This tutorial uses the Postman application, but you can use a different API development environment.

Important

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.
In the URL examples in this article you will need to replace {Your-Azure-Maps-Subscription-key} with your Azure Maps subscription key.

Upload a drawing package

Use the Data Upload API to upload the drawing package to Azure Maps resources.

The Data Upload API is a long running transaction that implements the pattern defined in Creator Long-Running Operation API V2.

To upload the drawing package:

In the Postman app, select New.
In the Create New window, select HTTP Request.
Enter a Request name for the request, such as POST Data Upload.
Select the POST HTTP method.

Enter the following URL to the Data Upload API The request should look like the following URL:

https://us.atlas.microsoft.com/mapData?api-version=2.0&dataFormat=dwgzippackage&subscription-key={Your-Azure-Maps-Subscription-key}

Select the Headers tab.
In the KEY field, select Content-Type.
In the VALUE field, select application/octet-stream.
Select the Body tab.
Select the binary radio button.
Select Select File, and then select a drawing package.
Select Send.
In the response window, select the Headers tab.
Copy the value of the Operation-Location key. The Operation-Location key is also known as the status URL and is required to check the status of the drawing package upload, which is explained in the next section.

Check the drawing package upload status

To check the status of the drawing package and retrieve its unique ID (udid):

In the Postman app, select New.
In the Create New window, select HTTP Request.
Enter a Request name for the request, such as GET Data Upload Status.
Select the GET HTTP method.
Enter the status URL you copied as the last step in the previous section of this article. The request should look like the following URL:
```
https://us.atlas.microsoft.com/mapData/operations/{operationId}?api-version=2.0&subscription-key={Your-Azure-Maps-Subscription-key}
```
Select Send.
In the response window, select the Headers tab.
Copy the value of the Resource-Location key, which is the resource location URL. The resource location URL contains the unique identifier (udid) of the drawing package resource.

(Optional) Retrieve drawing package metadata

You can retrieve metadata from the drawing package resource. The metadata contains information like the resource location URL, creation date, updated date, size, and upload status.

To retrieve content metadata:

In the Postman app, select New.
In the Create New window, select HTTP Request.
Enter a Request name for the request, such as GET Data Upload Metadata.
. Select the GET HTTP method.

Enter the resource Location URL you copied as the last step in the previous section of this article:

https://us.atlas.microsoft.com/mapData/metadata/{udid}?api-version=2.0&subscription-key={Your-Azure-Maps-Subscription-key}

Select Send.

In the response window, select the Body tab. The metadata should like the following JSON fragment:

{
    "udid": "{udid}",
    "location": "https://us.atlas.microsoft.com/mapData/6ebf1ae1-2a66-760b-e28c-b9381fcff335?api-version=2.0",
    "created": "5/18/2021 8:10:32 PM +00:00",
    "updated": "5/18/2021 8:10:37 PM +00:00",
    "sizeInBytes": 946901,
    "uploadStatus": "Completed"
}

Convert a drawing package

Now that the drawing package is uploaded, you'll use the udid for the uploaded package to convert the package into map data. The Conversion API uses a long-running transaction that implements the pattern defined in the Creator Long-Running Operation article.

To convert a drawing package:

In the Postman app, select New.
In the Create New window, select HTTP Request.
Enter a Request name for the request, such as POST Convert Drawing Package.
Select the POST HTTP method.

Enter the following URL to the Conversion service (replace {Your-Azure-Maps-Subscription-key} with your Azure Maps subscription key and udid with the udid of the uploaded package):

https://us.atlas.microsoft.com/conversions?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=2023-03-01-preview&udid={udid}&inputType=DWG&dwgPackageVersion=2.0

Select Send.
In the response window, select the Headers tab.
Copy the value of the Operation-Location key. This is the status URL that you'll use to check the status of the conversion.

Check the drawing package conversion status

After the conversion operation completes, it returns a conversionId. We can access the conversionId by checking the status of the drawing package conversion process. The conversionId can then be used to access the converted data.

To check the status of the conversion process and retrieve the conversionId:

In the Postman app, select New.
In the Create New window, select HTTP Request.
Enter a Request name for the request, such as GET Conversion Status.
Select the GET HTTP method:

Enter the status URL you copied in Convert a drawing package. The request should look like the following URL:

https://us.atlas.microsoft.com/conversions/operations/{operationId}?api-version=2.0&subscription-key={Your-Azure-Maps-Subscription-key}

Select Send.
In the response window, select the Headers tab.
Copy the value of the Resource-Location key, which is the resource location URL. The resource location URL contains the unique identifier (conversionId), which can be used by other APIs to access the converted map data.

The sample drawing package should be converted without errors or warnings. However, if you receive errors or warnings from your own drawing package, the JSON response includes a link to the Drawing error visualizer. You can use the Drawing Error visualizer to inspect the details of errors and warnings. To receive recommendations to resolve conversion errors and warnings, see Drawing conversion errors and warnings.

The following JSON fragment displays a sample conversion warning:

{
    "operationId": "{operationId}",
    "created": "2021-05-19T18:24:28.7922905+00:00",
    "status": "Succeeded",
     "warning": {
        "code": "dwgConversionProblem",
        "details": [
            {
                "code": "warning",
                "details": [
                    {
                        "code": "manifestWarning",
                        "message": "Ignoring unexpected JSON property: unitProperties[0].nonWheelchairAccessible with value False"
                    }
                ]
            }
        ]
    },
    "properties": {
        "diagnosticPackageLocation": "https://atlas.microsoft.com/mapData/ce61c3c1-faa8-75b7-349f-d863f6523748?api-version=1.0"
    }
}

Create a dataset

A dataset is a collection of map features, such as buildings, levels, and rooms. To create a dataset, use the Dataset Create API. The Dataset Create API takes the conversionId for the converted drawing package and returns a datasetId of the created dataset.

To create a dataset:

In the Postman app, select New.
In the Create New window, select HTTP Request.
Enter a Request name for the request, such as POST Dataset Create.
Select the POST HTTP method.
Enter the following URL to the Dataset service. The request should look like the following URL (replace {conversionId} with the conversionId obtained in Check drawing package conversion status):
```
https://us.atlas.microsoft.com/datasets?api-version=2023-03-01-preview&conversionId={conversionId}&subscription-key={Your-Azure-Maps-Subscription-key}
```
Select Send.
In the response window, select the Headers tab.
Copy the value of the Operation-Location key. This is the status URL that you'll use to check the status of the dataset.

Check the dataset creation status

To check the status of the dataset creation process and retrieve the datasetId:

In the Postman app, select New.
In the Create New window, select HTTP Request.
Enter a Request name for the request, such as GET Dataset Status.
Select the GET HTTP method.

Enter the status URL you copied in Create a dataset. The request should look like the following URL:

https://us.atlas.microsoft.com/datasets/operations/{operationId}?api-version=2023-03-01-preview&subscription-key={Your-Azure-Maps-Subscription-key}

Select Send.
In the response window, select the Headers tab. The value of the Resource-Location key is the resource location URL. The resource location URL contains the unique identifier (datasetId) of the dataset.
Save the datasetId value, because you'll use it in the next tutorial.

Create a tileset

A tileset is a set of vector tiles that render on the map. Tilesets are created from existing datasets. However, a tileset is independent from the dataset from which it was sourced. If the dataset is deleted, the tileset continues to exist.

To create a tileset:

In the Postman app, select New.
In the Create New window, select HTTP Request.
Enter a Request name for the request, such as POST Tileset Create.
Select the POST HTTP method.
Enter the following URL to the Tileset service. The request should look like the following URL (replace {datasetId} with the datasetId obtained in the Check the dataset creation status section above:
```
https://us.atlas.microsoft.com/tilesets?api-version=2023-03-01-preview&datasetID={datasetId}&subscription-key={Your-Azure-Maps-Primary-Subscription-key}
```
Select Send.
In the response window, select the Headers tab.
Copy the value of the Operation-Location key, this is the status URL, which you'll use to check the status of the tileset.

Check the tileset creation status

To check the status of the tileset creation process and retrieve the tilesetId:

In the Postman app, select New.
In the Create New window, select HTTP Request.
Enter a Request name for the request, such as GET Tileset Status.
Select the GET HTTP method.

Enter the status URL you copied in Create a tileset. The request should look like the following URL:

https://us.atlas.microsoft.com/tilesets/operations/{operationId}?api-version=2023-03-01-preview&subscription-key={Your-Azure-Maps-Subscription-key}

Select Send.
In the response window, select the Headers tab. The value of the Resource-Location key is the resource location URL. The resource location URL contains the unique identifier (tilesetId) of the dataset.

The map configuration (preview)

Once your tileset creation completes, you can get the mapConfigurationId using the tileset get HTTP request:

In the Postman app, select New.
In the Create New window, select HTTP Request.
Enter a Request name for the request, such as GET mapConfigurationId from Tileset.
Select the GET HTTP method.

Enter the following URL to the Tileset service, passing in the tileset ID you obtained in the previous step.

https://us.atlas.microsoft.com/tilesets/{tilesetId}?api-version=2022-09-01-preview&subscription-key={Your-Azure-Maps-Subscription-key}

Select Send.
The tileset JSON will appear in the body of the response, scroll down to see the mapConfigurationId:
```
"defaultMapConfigurationId": "5906cd57-2dba-389b-3313-ce6b549d4396"
```

For more information, see Map configuration in the indoor maps concepts article.

Next steps

Use the Azure Maps Indoor Maps module with custom styles