API Reference

The MyGeodata Cloud API allows you to process your data in a simple, programmatic way using conventional HTTP requests from any language. In the following examples, we use the cURL command, a common tool for testing API services.

To use our API you will need an API key, which you can generate in your user profile.

API Key Authentication

To authenticate API requests, you can provide your API_KEY in one of the following ways:

Authorization Header:

Include the API_KEY in the Authorization header. The header should be formatted as follows:

Authorization: Bearer API_KEY

Example curl command:

curl https://api.mygeodata.cloud/v1/test -H "Authorization: Bearer API_KEY"

x-api-key Header:

Alternatively, you can pass the API_KEY in the x-api-key header:

x-api-key: API_KEY

Example curl command:

curl https://api.mygeodata.cloud/v1/test -H "x-api-key: API_KEY"

POST Parameter or JSON Payload:

You can also include the API_KEY as a parameter in the POST request body or JSON payload of the POST request. For example:

{
  "api_key": "API_KEY",
  "other_param": "value"
}

Example curl command for JSON Payload:

curl https://api.mygeodata.cloud/v1/test -H "Content-Type: application/json" -X POST -d '{"api_key":"API_KEY", "other_param":"value"}'

Example curl command for POST form data:

curl --header "Content-Type: multipart/form-data" --request POST --form 'api_key=API_KEY' --form 'other_param=value' https://api.mygeodata.cloud/v1/test

GET Parameter:

For GET requests, you can pass the API_KEY as a query parameter in the URL:

https://api.mygeodata.cloud/v1/test?api_key=API_KEY&other_param=value

Convert Method

Converts the provided vector or raster data to the selected format or coordinate system.

Endpoint: https://api.mygeodata.cloud/v1/convert

Request Parameters

Parameter	Type	Description
file1, file2, ...	file (binary)	The file or files to be uploaded. This parameter(s) should contain the binary data of the file being uploaded, using multipart/form-data content type. If the dataset contains multiple files, then they can be uploaded as multiple attachments or packed into a single ZIP file. The archive will be unpacked automatically on the server.
src_url	string	Instead of sending the binary data directly by the API, it is possible to reference the input files using a URL. The service will download this data from the URL and use it as input data. The URL must be accessible to the server without authentication. If multiple files need to be passed to the service at once, they must be packed (e.g. in a ZIP) and referenced to this single packed file that contains all the necessary files.
format	string	Code of the required output data format. For vector data it can be one of the following: KML, KMZ, ESRI Shapefile, CSV, XLSX, ODS, GeoJSON, GPKG, SQLite, FlatGeobuf, Parquet, SVG, GPX, GML, MapInfo File TAB, MapInfo File MIF/MID, DXF, DGN, OpenFileGDB, MVT, TopoJSON, PDF. For raster data: GTiff, GPKG, MBTiles, KMLSuperoverlay, JPEG, PNG, AAIGrid, JP2OpenJPEG, PDF, XYZ, ...
out_crs	string	The desired output coordinate reference system (CRS). If the output CRS is not specified, then the resulting data has the same coordinate system as the input data. However, this does not apply to some output formats that have a coordinate system fixed by a given standard - e.g. KML, KMZ, GPX, GeoJSON always have WGS 84, or MBTiles always have WGS 84 / Pseudo-Mercator. For other output formats, the desired CRS can be defined using EPSG codes, e.g. EPSG:4326 for WGS 84. Alternatively, it is possible to use a well known text (WKT) CRS definition or PROJ.4 declarations.
in_crs	string	For input data that does not include information about the coordinate system used, it is possible to assign the corresponding coordinate system using this parameter. The CRS can be defined using EPSG codes, e.g. EPSG:4326 for WGS 84. Alternatively, it is possible to use a well known text (WKT) CRS definition or PROJ.4 declarations.
output	string	By default, the resulting data is returned in binary form (binary/octet-stream) for saving to a file. This corresponds to the output=binary option. Alternatively, it is possible to return a URL from which the result can be downloaded (output=url).
force_zip	string	If there is only one resulting file, it will be returned as is - unwrapped. If the result contains more than one file, the result files are automatically packed into a single ZIP file (regardless of this parameter). If it is preferred to always get the result as a ZIP file (even if there is only one file in the result), this can be achieved with the force_zip=1 option.
zipname	string	By default, the resulting ZIP file is named mygeodata.zip. Using this parameter, the file name can be changed, e.g.: zipname=myResult produces myResult.zip file.
data_type	string	Some formats can contain both raster and vector data simultaneously. To avoid confusion as to which type of data to convert, this can be specified with the vector or raster value of this parameter.
merge	string	If the conversion creates multiple output datasets, it can combine them into a single dataset whenever possible. This can be achieved with the merge=1 option. Please note that some combinations of geometry types, the existence of multiple layers in the input files, and output format limitations make it impossible to merge the resulting files and the merge may not be successful.
layers	string	If the input vector data contains multiple layers, this parameter can be used to select a specific layer or multiple layers (separated by a comma) for processing, for example: layers=Buildings,Streets.
nln	string	The new layer name parameter (nln) allows you to set a new name for the layer in the resulting vector data, e.g.: nln=DataFolder
fields	string	Allows you to select and rename field names for the output vector data. For example, it is possible to choose only certain fields (attributes) from the input data and rename them as needed by defining them using fields=id,value,Text=Name,img=Images.
namefield	string	Allows you to specify the field from input vector data to use for the KML <name> element - to label the popup window in Google Earth, e.g.: namefield=Text.
descriptionfield	string	Allows you to specify the field from input vector data to use for the KML <description> element - to specify which field value will be displayed in the popup window in Google Earth, e.g.: descriptionfield=imageUrlHtml
config	string	Allows you to specify various conversion configuration parameters. For example config=OGR_ARC_STEPSIZE:1 sets the approximation of arcs when converting to linestring to angle of 1˚. In case of multiple parameters, the individual parameters can be separated by a comma,

Examples

Example of API call using curl command and POST request, sending files as multipart form data:

curl -H "Content-Type: multipart/form-data" -X POST -F 'api_key=API_KEY' -F 'format=ESRI Shapefile' -F 'in_crs=EPSG:28992' -F 'out_crs=EPSG:4326' -F "file1=@/path/file1.dxf" --output result.zip https://api.mygeodata.cloud/v1/convert

Example of API GET request URL:

https://api.mygeodata.cloud/v1/convert?api_key=API_KEY&format=CSV&output=url&src_url=https://mygeodata.cloud/examples/data/NY.geojson

Dataset info

For those who want to verify that their input data is supported by the Converter and see what it contains. Returns a JSON object (application/json) describing geospatial data that user sent by the API.

Endpoint: https://api.mygeodata.cloud/v1/datasetinfo

Request Parameters

Parameter	Type	Description
file1, file2, ...	file (binary)	The file or files to be uploaded. This parameter(s) should contain the binary data of the file being uploaded, using multipart/form-data content type. If the dataset contains multiple files, then they can be uploaded as multiple attachments or packed into a single ZIP file. The archive will be unpacked automatically on the server.
src_url	string	Instead of sending the binary data directly by the API, it is possible to reference the input files using a URL. The service will download this data from the URL and use it as input data. The URL must be accessible to the server without authentication. If multiple files need to be passed to the service at once, they must be packed (e.g. in a ZIP) and referenced to this single packed file that contains all the necessary files.
output	string	By default, the data is returned in JSON format (output=json). Alternatively, the output can be formatted as text - using the output=text parameter.

Examples

Example of API call using curl command and POST request, sending files as multipart form data:

curl -H "Content-Type: multipart/form-data" -X POST -F 'api_key=API_KEY' -F "file1=@/path/file1.dxf" -F "file2=@/path/file1.prj" https://api.mygeodata.cloud/v1/datasetinfo

Example of API GET request URL:

https://api.mygeodata.cloud/v1/datasetinfo?api_key=API_KEY&src_url=https://mygeodata.cloud/examples/data/NY.geojson

Response

A successful response will return a 200 status code with the JSON data describing input geospatial data. The resulting JSON data is structured in a way that contains summary information for all uploaded data together, for individual data types (vector, raster) and for individual data files, e.g.:

{
    "success": true,
    "data": {
        "crss": [
            "EPSG:4269"
        ],
        "crss_named": [
            "NAD83 (EPSG:4269)"
        ],
        "extent": [
            -74.24856546578718,
            40.49956561284709,
            -73.73228708990119,
            40.89620924089748
        ],
        "extentOrig": [
            -74.24856463534954,
            40.49956588939512,
            -73.73228698411847,
            40.896209869557374
        ],
        "size": 31424,
        "vector": {
            "crss": [
                "EPSG:4269"
            ],
            "drivers": [
                "GeoJSON"
            ],
            "drivers_named": [
                "GeoJSON"
            ],
            "dsCnt": 1,
            "dss": [
                {
                    "crss": [
                        "EPSG:4269"
                    ],
                    "driver": "GeoJSON",
                    "extent": [
                        -74.24856546578718,
                        40.49956561284709,
                        -73.73228708990119,
                        40.89620924089748
                    ],
                    "extentOrig": [
                        -74.24856463534954,
                        40.49956588939512,
                        -73.73228698411847,
                        40.896209869557374
                    ],
                    "featuresCnt": 96,
                    "files": [
                        "NY.geojson"
                    ],
                    "geomTypes": [
                        "Point"
                    ],
                    "layers": [
                        {
                            "attributes": [
                                {
                                    "name": "Id",
                                    "type": "Integer"
                                },
                                ...
                            ],
                            "attributesCnt": 10,
                            "crs": "EPSG:4269",
                            "extent": [
                                -74.24856546578718,
                                40.49956561284709,
                                -73.73228708990119,
                                40.89620924089748
                            ],
                            "extentOrig": [
                                -74.24856463534954,
                                40.49956588939512,
                                -73.73228698411847,
                                40.896209869557374
                            ],
                            "featuresCnt": 96,
                            "geomType": "Point",
                            "geomTypes": [
                                "Point"
                            ],
                            "geometryName": "GEOMETRY",
                            "name": "NY",
                            "units": "degrees"
                        }
                    ],
                    "layersCnt": 1,
                    "size": 31424,
                    "units": [
                        "degrees"
                    ]
                }
            ],
            "extent": [
                -74.24856546578718,
                40.49956561284709,
                -73.73228708990119,
                40.89620924089748
            ],
            "extentOrig": [
                -74.24856463534954,
                40.49956588939512,
                -73.73228698411847,
                40.896209869557374
            ],
            "featuresCnt": 96,
            "geomTypes": [
                "Point"
            ],
            "layersCnt": 1,
            "size": 31424,
            "units": [
                "degrees"
            ]
        }
    }
}

Program Code Examples

Here are some examples of how to convert files using different programming languages:

Python

import requests

url = "https://api.mygeodata.cloud/v1/convert"
files = {'file1': open("/path/file.dxf", 'rb')}
data = {
    'api_key': "API_KEY",
    'format': "ESRI Shapefile",
    'in_crs': "EPSG:28992",
    'out_crs': "EPSG:4326"
}

response = requests.post(url, files=files, data=data)

if response.status_code == 200:
    with open('result.zip', 'wb') as f:
        f.write(response.content)
    print("Conversion complete and file saved as 'result.zip'")
else:
    print(f"Error when calling API: {response.status_code}, {response.text}")

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Path;
import java.nio.file.Paths;

public class ApiFileUpload {

    public static void main(String[] args) throws Exception {
        String url = "https://api.mygeodata.cloud/v1/convert";
        String apiKey = "API_KEY";
        String format = "ESRI Shapefile";
        String inCrs = "EPSG:28992";
        String outCrs = "EPSG:4326";
        Path filePath = Paths.get("/path/file1.dxf");

        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Content-Type", "multipart/form-data; boundary=boundary123")
            .POST(HttpRequest.BodyPublishers.ofString(
                    "--boundary123\r\n" +
                    "Content-Disposition: form-data; name=\"api_key\"\r\n\r\n" + apiKey + "\r\n" +
                    "--boundary123\r\n" +
                    "Content-Disposition: form-data; name=\"format\"\r\n\r\n" + format + "\r\n" +
                    "--boundary123\r\n" +
                    "Content-Disposition: form-data; name=\"in_crs\"\r\n\r\n" + inCrs + "\r\n" +
                    "--boundary123\r\n" +
                    "Content-Disposition: form-data; name=\"out_crs\"\r\n\r\n" + outCrs + "\r\n" +
                    "--boundary123\r\n" +
                    "Content-Disposition: form-data; name=\"file1\"; filename=\"" + filePath.getFileName() + "\"\r\n" +
                    "Content-Type: application/octet-stream\r\n\r\n" +
                    new String(java.nio.file.Files.readAllBytes(filePath)) + "\r\n" +
                    "--boundary123--\r\n"))
            .build();

        HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofFile(Paths.get("result.zip")));

        if (response.statusCode() == 200) {
            System.out.println("Conversion complete and file saved as 'result.zip'");
        } else {
            System.out.println("Error when calling API: " + response.statusCode());
        }
    }
}

C#

using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        string url = "https://api.mygeodata.cloud/v1/convert";
        string apiKey = "API_KEY";
        string format = "ESRI Shapefile";
        string inCrs = "EPSG:28992";
        string outCrs = "EPSG:4326";
        string filePath = "/path/file1.dxf";

        using (var client = new HttpClient())
        using (var form = new MultipartFormDataContent())
        {
            form.Add(new StringContent(apiKey), "api_key");
            form.Add(new StringContent(format), "format");
            form.Add(new StringContent(inCrs), "in_crs");
            form.Add(new StringContent(outCrs), "out_crs");

            var fileContent = new StreamContent(File.OpenRead(filePath));
            fileContent.Headers.ContentType = MediaTypeHeaderValue.Parse("application/octet-stream");
            form.Add(fileContent, "file1", Path.GetFileName(filePath));

            var response = await client.PostAsync(url, form);

            if (response.IsSuccessStatusCode)
            {
                var result = await response.Content.ReadAsByteArrayAsync();
                File.WriteAllBytes("result.zip", result);
                Console.WriteLine("Conversion complete and file saved as 'result.zip'");
            }
            else
            {
                Console.WriteLine($"Error when calling API: {response.StatusCode}, {await response.Content.ReadAsStringAsync()}");
            }
        }
    }
}

HTML / JavaScript

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>File Upload API</title>
    <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
</head>
<body>
    <input type="file" id="fileInput" />
    <button id="uploadBtn">Upload File</button>

    <script>
        $(document).ready(function () {
            $('#uploadBtn').click(function () {
                var fileInput = document.getElementById('fileInput');
                var file = fileInput.files[0];

                var formData = new FormData();
                formData.append('api_key', 'API_KEY');
                formData.append('format', 'ESRI Shapefile');
                formData.append('in_crs', 'EPSG:28992');
                formData.append('out_crs', 'EPSG:4326');
                formData.append('file1', file);

                $.ajax({
                    url: 'https://api.mygeodata.cloud/v1/convert',
                    type: 'POST',
                    data: formData,
                    contentType: false,
                    processData: false,
                    xhrFields: {
                        responseType: 'blob'
                    },
                    success: function (response) {
                        var url = window.URL.createObjectURL(response);
                        var a = document.createElement('a');
                        a.style.display = 'none';
                        a.href = url;
                        a.download = 'result.zip';
                        document.body.appendChild(a);
                        a.click();
                        window.URL.revokeObjectURL(url);
                        alert('Conversion complete and file saved.');
                    },
                    error: function (jqXHR, textStatus, errorThrown) {
                        console.log('Error when calling API:', textStatus, errorThrown);
                    }
                });
            });
        });
    </script>
</body>
</html>

PHP

<?php

$file = new CURLFile("/path/file.dxf");

$data = [
    'api_key' => "API_KEY",
    'format' => "ESRI Shapefile",
    'in_crs' => "EPSG:28992",
    'out_crs' => "EPSG:4326",
    'file1' => $file
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.mygeodata.cloud/v1/convert");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Content-Type: multipart/form-data"
));

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'cURL error: ' . curl_error($ch);
} else {
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if ($httpCode == 200) {
        file_put_contents('result.zip', $response);
        echo "Conversion complete and file saved as 'result.zip'";
    } else {
        echo "Error when calling API: HTTP code " . $httpCode;
    }
}

curl_close($ch);

Ruby

require 'net/http'
require 'uri'
require 'json'

url = URI.parse('https://api.mygeodata.cloud/v1/convert')
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
form_data = [
  ['api_key', 'API_KEY'],
  ['format', 'ESRI Shapefile'],
  ['in_crs', 'EPSG:28992'],
  ['out_crs', 'EPSG:4326'],
  ['file1', File.open('/path/file.dxf')]
]

request.set_form(form_data, 'multipart/form-data')
response = http.request(request)

if response.is_a?(Net::HTTPSuccess)
  File.open('result.zip', 'wb') do |file|
    file.write(response.body)
  end
  puts "Conversion complete and file saved 'result.zip'"
else
  puts "Error when calling API: #{response.code} #{response.message}"
end

Error Codes

If there is an error with your request, you will receive an appropriate HTTP status code and message.

Status Code	Error	Description
204	No Content	No relevant data were found in the input files. This can happen if your input data format is not supported or data is corrupted.
400	Bad Request	Invalid input parameters.
401	Unauthorized	Invalid or missing API key.
405	Unsupported HTTP method	POST or GET method is required.
408	Request Timeout	The request took too long to complete. Please consider using an asynchronous call (not implemented yet).
415	Unsupported content type	Supported content types: application/json, application/x-www-form-urlencoded, multipart/form-data
500	Unknown Error	There was an unknown error. Make sure that your input files are not corrupted and that all the parameters you have provided are correct.