Simple Exports

As the name suggests, the Simple Export API provides an easy interface to generate and download files. The best available data sources for the requested bounding box and feature types are automatically chosen.

How it works

Downloading a custom file is a three-step process:

Start a new export job by providing a bounding box, a center point, or an address.
Check the status of the export job using the GET /api/export/:id endpoint.
Download the zip file using the provided download_url.

Python example

POST/api/export/simple

Start a new export

This endpoint allows you to create a new export job. The export will be processed asynchronously, and you can check the status of the export using the GET /api/export/:id endpoint.

Only an area definition is required to get started. You can provide either a bounding box, a center point, or an address.

In case you provide a center point or an address, the bounding box will be calculated automatically using the size attribute.

Required attributes (one of)

Name
bbox
Type
array[number]
Description
The bounding box in WGS84 coordinates.
[minLon, minLat, maxLon, maxLat]
Name
center
Type
array[number]
Description
The center of the bounding box in WGS84 coordinates.
[lon, lat]
Name
address
Type
string
Description
The address of the center point.

Optional attributes

Name
format
Type
enum
Description
Format of the output file.
- stl
- obj
- dxf
Default
Default: stl
Name
size
Type
array[number]
Description
The size of the bounding box surrounding the center point in meters. Only relevant together with 'center' or 'address'.
[width, height]
'width' is from west to east, 'height' is from south to north.
Default
Default: [500, 500]
Name
include
Type
array[string]
Description
The features to include in the export.
- terrain
- buildings
Default
Default: ['terrain']
Name
separate_files
Type
array[string]
Description
If true, each feature will be exported to a separate file.
Default
Default: false
Name
terrain_texture
Type
enum
Description
If set, the terrain will be textured. Only available if terrain is included.
- map : Textured with a map image.
- dop : Textured with a digital orthophoto. (arial image)
Name
translate_to_origin
Type
bool
Description
If true, the model will be translated to the origin.
Default
Default: true
Name
srs_epsg
Type
number
Description
EPSG code of the SRS used for the output file. Defaults to the terrain's native coordinate system. Supported: 3857

Response attributes

The response contains a lot of information about the export and used data sources. The most important are:

Name
id
Type
string
Description
The ID of the export job. Save this ID to check the status later.
Name
status
Type
enum
Description
The status of the export job.
States: pending, running, done, failed
Name
price
Type
number
Description
The price of the export job in EUR cents. 0 if free. Divide by 100 to get the price in EUR.
Example: 1000 = 10 EUR
The price is only charged if the export is successful and the file is downloaded.
Name
target_epsg
Type
number
Description
The EPSG code of the output file.

Request

POST

/api/export/simple

curl 'https://v2.3dcityloader.com/api/export/simple' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "address": "Köln, Deutschland",
    "format": "stl",
    "include": ["terrain", "buildings"],
    "size": [500,500]
    }'

Response

{
  "id": "9e709145-708b-42a6-829e-11cef4d4ca7a",
  "status": "pending",
  "price": 0,
  "target_epsg": 25832
}

GET/api/export/:id

Retrieve status

This endpoint allows you to retrieve a contact by providing their Protocol ID. Refer to the list at the top of this page to see which properties are included with contact objects.

Response attributes

The response contains a lot of information about the export and the data sources used. The most important attributes are:

Name
status
Type
enum
Description
The status of the export job. The files are only available if the status is 'done'. States: pending, running, done, failed.
Name
download_url
Type
string | null
Description
The URL to download the file. Only available if the status is 'done'. Requests to this URL are redirected to a signed URL with a limited lifetime. Make sure your HTTP client follows redirects.
By sending a request, your account will be charged for the export job. You can download the file as often as you need within 14 days.
Name
preview_url
Type
string
Description
The URL to a PNG preview image of the export.
Name
price
Type
number
Description
The price of the export job in EUR cents. 0 if free. Divide by 100 to get the price in EUR.
Example: 1000 = 10 EUR
The price is only charged if the export is successful and the file is downloaded.

Request

GET

/api/export/:id

curl https://v2.3dcityloader.com/api/export/9e709145-708b-42a6-829e-11cef4d4ca7a \
  -H "Authorization: Bearer <token>"

Response

{
  "status": "done",
  "download_url": "https://v2.3dcityloader.com/export/9e709145-708b-42a6-829e-11cef4d4ca7a/download?signature=...",
  "preview_url": "https://3dcl-previews.s3.eu-central-1.amazonaws.com/9e709145-708b-42a6-829e-11cef4d4ca7a.png",
  "price": 0
}

Download

To download the files, simply send a GET request to the provided download_url. This request will be redirected to a signed URL with a limited lifetime. Make sure your HTTP client follows redirects.

The files will be provided as a ZIP archive. Depending on the format and features you requested, the ZIP archive may contain multiple files. Here is a list of files you can expect:

Name
{id}.{format}
Type
stl, obj or dxf
Description
A 3D model of all requested features in the chosen file format, or only the terrain if 'separate_files' is set.
Name
{id}_{layer}.{format}
Type
stl, obj or dxf
Description
A 3D model of a single feature in the chosen file format. Only available if 'separate_files' is set.
Name
texture.jpg
Type
jpg
Description
Texture image for the terrain. Only available if 'terrain_texture' is set and the 'obj' format is chosen.
Name
texture.wld
Type
wld
Description
World file for the texture image. Only available if 'terrain_texture' is set and the 'obj' format is chosen. Contains the georeferencing information for the texture image. Only relevant if you want to use the texture in GIS software.
Name
ATTRIBUTION.txt
Type
txt
Description
Attribution information for the used data sources. Must be included in any publication of the data.

Pricing

The price of the export job is dynamically calculated based on the area and features you request. You will find it in the returned 'price' attribute. The price is only charged if the export is successful and the file is downloaded. You can download the file as often as you need within 14 days.

So you can create a new export and check the preview free of charge before you decide to download and pay for the file.

The quota of available previews is limited to prevent abuse, so please use it responsibly.

You can find your current balance and a detailed list of all charges in your billing settings.

Areas smaller than 500m² are free of charge, so you can test the API and your integration without any costs. You can also unset the export.pay permission for an API token to prevent any accidental costs while testing.

Feel free to contact us for bulk discounts or if you have any questions regarding the pricing. We're happy to help and will find a pricing model that fits your business.