API

Quickstart

This guide will get you all set up and ready to use the Simple Export API to create and download files for a custom area.

Before you can make requests to the API, you will need to create an API token for your account and ensure that a valid payment method is set up. You can find it under Account Settings » API Tokens. Adding a payment method will not trigger any costs; you will only be charged for the services you use.

The permissions export.create, export.read, and export.pay are required to use the Simple Export API.
To prevent any accidental costs while testing, you can unset the export.pay permission for an API token.

How to use the Simple Export API

The file generation process is asynchronous and consists of three steps:

  1. Start a new export job.
  2. Poll for the export status until it is done.
  3. Download the ZIP file using the provided download_url.

In this guide, we'll walk you through the steps to create a new export job and download the file using the Python requests library.

1. Create a new export job

To create a new export job, you need to send a POST request to the /api/export/simple endpoint with a JSON body containing the export configuration. The configuration can include the area you want to export, the file format, and other options.

You can provide either a bounding box, a center point, or an address. If you provide a center point or an address, the bounding box will be calculated automatically using the size attribute. Below, you can see an example of how to create a new export job using a bounding box, center, or address. In this example, an STL file with terrain and buildings is requested.

Check out all export options
POST
/api/export/simple
    curl 'http://v2.3dcityloader.com/api/export/simple' \
    -H 'Authorization: Bearer <token>' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
        "bbox": [6.9539,50.9407,6.9592,50.9439],
        "format": "stl",
        "include": ["terrain", "buildings"]
        }'

Replace <token> with your API token.

The response will contain the id of the export job. You need to save this ID to poll for the export status and download the file in the next steps.

2. Poll for the export status

After creating the export job, you need to poll the /api/export/:id endpoint to check the status of the export job. The status can be pending, processing, done, or failed. You can poll the endpoint every few seconds until the status is done or failed.

POST
/api/export/simple
    curl 'http://v2.3dcityloader.com/api/export/:id' \
        -H 'Authorization: Bearer <token>' \
        -H 'Content-Type: application/json' \
        -H 'Accept: application/json'

Replace :id with the ID of the export job you received in the previous step.

3. Download the files

When the status of the export job is done, the response will contain a download_url. You can use this URL to download the ZIP file containing the exported data.

Python Example

Below is a Python example that demonstrates how to create a new export job, poll for the status, and download the file using the Python requests library. You can run this code in your local Python environment. Make sure to install the requests library using pip install requests before running the code. You also need to replace <your-api-token> with a valid one.

import requests
import json
import time
import zipfile
import io

# Function for polling the export status until it's ready for download
def poll_until_done(export_id):
    time.sleep(4)
    while True:
        response = requests.get(
            f'{endpoint}/export/{export_id}',
            headers={
                'Authorization': f'Bearer {api_token}',
                'Content-Type': 'application/json',
                'Accept': 'application/json'
            }
        )
        if response.status_code != 200:
            raise Exception(f'Error {response.status_code} : {response.json().get("message")}')
        
        export_info = response.json()
        
        if export_info.get('status') == 'done':
            return export_info.get('download_url')
        
        if export_info.get('status') == 'failed':
            raise Exception("Export failed.")

        # Wait for 3 seconds before polling again
        time.sleep(3)

# Create a new export job
def create_export(config):
    response = requests.post(
        f'{endpoint}/export/simple',
        headers={
            'Authorization': f'Bearer {api_token}',
            'Content-Type': 'application/json',
            'Accept': 'application/json'
        },
        json=config
    )
    data = response.json()
    if response.status_code != 201:
        raise Exception(f'Error {response.status_code} : {data.get("message")}')
    return data.get('id')
    

# The 3DCityLoader custom API endpoint, no need to change
endpoint = 'https://v2.3dcityloader.com/api'

# Your API Token from https://v2.3dcityloader.com/user/api-tokens
#  with permission "export.create", "export.read" and ("export.pay") set
api_token = '<your-api-token>'

# The JSON export config
export_config = {
    'bbox': [6.761024,51.219985,6.771285,51.226381],
    'format': 'stl',
    'include': ['buildings', 'terrain'],
}

# Create a new export and save the returned id
export_id = create_export(export_config)

print(f'Export Job created with id: {export_id} ,start polling for status')

# Start polling until the export is done and retirve the download url from the repsonse
download_url = poll_until_done(export_id)
print('Export ready for download. Downloading...')

#Download and extract the zip file from the url. !allow_redirects musst be enabled!
r = requests.get(download_url, allow_redirects=True, stream=True)

# Extract the zip file, using s
zipfile = zipfile.ZipFile(io.BytesIO(r.content))
zipfile.extractall(f'./download/{export_id}')

print(f'Request file downloaded to ./download/{export_id}/{export_id}.stl')

What's next?

Great, you've now downloaded your first files using the API. Here are a few links that might be handy as you explore the Simple Export API:

If you have any questions or need help, feel free to reach out to support.

Was this page helpful?