---
title: "Import KML / KMZ"
section: "API Reference"
route: /apiimportkml
account: {accountId}
bruce_api: https://{accountId}.api.nextspace.host
guardian_api: https://guardian.nextspace.host
---
# Import KML / KMZ

You can mimic the import functionality you see in Operator by making your own import process for KML files.

We'll assume you know how to upload files through the API and that you have access to a `TempFile.ID` or `ClientFile.ID`.

## Analysis

This is an **optional** step to the process that gets you a list of KML folders and attribute definitions for data mapping.

In Operator, this step lets the user map KML folders to Entity Types, and adjust the data mapping for each folder.

### KML Analysis

```http
POST https://{accountId}.api.nextspace.host/import/analyze/kml
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Power user auth token: A token for an active power user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |

**Request body**

```typescript
interface IPostBody {
    // Previously uploaded temp file ID or Client File ID.
    // One of these is required.
    "TempFile.ID": string;
    // File name used for creating an import record.
    // Eg: 'my-file.kml'.
    // If you specify a Client File ID, this is not needed as the name is already known.
    "TempFile.Name": string;
    "ClientFile.ID": string;
}
```

**Example request body**

```json
{
    "TempFile.ID": "abc",
    "TempFile.Name": "my-file.kml"
}
```

**Response**

```typescript
interface IResponse {
    "PendingActionID": number;
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/import/analyze/kml";
const method = "post";
const token = "your-token";
const body = {
    "TempFile.ID": "abc",
    "TempFile.Name": "my-file.kml"
};

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

When the Pending Action is marked as completed, here is the result to expect:

```typescript
interface IResult {
    "KMLFolders": {
        "ID": string;
        "Name": string;
        "DataSchema": any;
        "PlacemarksCount": number;
        "PolygonsCount": number;
    }[];
}
```

## Import

### KML Import

```http
POST https://{accountId}.api.nextspace.host/import/kml
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Power user auth token: A token for an active power user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |

**Request body**

```typescript
interface IPostBody {
    // Previously uploaded temp file ID or Client File ID.
    // One of these is required.
    "TempFile.ID": string;
    // File name used for creating an import record.
    // Eg: 'my-file.kml'.
    // If you specify a Client File ID, this is not needed as the name is already known.
    "TempFile.Name": string;
    "ClientFile.ID": string;

    // Optional analysis ID to reference.
    // This is used to estimate import progress as analysis includes counts.
    "Analysis.PendingAction.ID"?: number;

    // Specifies how the features should be imported.
    // Eg: 'A' for add, 'U' for update, 'R' for replace (delete before importing).
    // You can also use 'U+A' to update or add (our default).
    // Or 'U+A+D' to update or add, then delete any Entities not in the KML.
    // These are all relative to the specified Entity Type.
    "ImportMode": "A" | "U" | "R" | "U+D" | "U+A" | "U+D+A";

    // Settings per KML folder for the import.
    // At least one folder is required.
    "KMLFolders": {
        "KMLFolder.ID": string;
        // Destination Entity Type.
        "EntityType.ID": string;
        // Array of Nextspace Tag IDs to apply to all imported Entities.
        "AddLayerIDs"?: number[];
        // Data mapping for the KML properties to the target Entity Type schema.
        "DataMapping"?: any;

        // Key of the LOD Category to use for imported LOD files.
        // Default is 'GLB'.
        "LODCategory.Key"?: string;
        // LOD Level to use for imported LOD files.
        // Default is 0 (best quality).
        "LODLevel"?: number;
        // Scale factor applied to 'DAE' -> 'GLB' conversion during import.
        // Default is 1.0 (no scaling).
        "ConversionScale"?: number;
    }[];
}
```

**Example request body**

```json
{
    "TempFile.ID": "blah-abc",
    "TempFile.Name": "my-file.kml",
    "ImportMode": "A",
    "Analysis.PendingAction.ID": 1
}
```

**Response**

```typescript
interface IResponse {
    "PendingActionID": number;
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/import/kml";
const method = "post";
const token = "your-token";
const body = {
    "TempFile.ID": "blah-abc",
    "TempFile.Name": "my-file.kml",
    "ImportMode": "A",
    "Analysis.PendingAction.ID": 1
};

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

When the Pending Action is marked as completed, here is the result to expect:

```typescript
interface IResult {
    // Number of failed to import features.
    "CountFailed": number;
    // Number of successfully imported features.
    "CountImported": number;
}
```

---

Urls on this page are resolved for account `{accountId}`.
Site index: https://docs.nextspace.host/llms.txt · whole site in one file: https://docs.nextspace.host/llms-full.txt
Human-readable version of this page: https://docs.nextspace.host/apiimportkml