Skip to main content

Append

GeoFlip’s append endpoints allow developers to add spatial data to existing datasets, accommodating all of Geoflip's currently supported data formats such as GeoJSON, Shapefile (SHP), DXF, and GeoPackage (GPKG). This guide provides an overview of the principles and structure for using these endpoints effectively, covering common parameters, authentication, and request formats.

The append operation requires a target file (or geojson feature set) along with any number of additional files.

Append Illustration

Things to keep in mind when performing append:

  • All files must be of the same file format
  • If performing the append on data with no inherently defined CRS (ie DXF) you must provide crs information
    • use the input_crs config parameter to define the crs of the target file
    • use the append_crs_mapping config parameter to define the crs of the append files
      • this can be a list of CRS values (ie "EPSG:4326") in the same order as the submitted files or a single CRS which is to be used for all append files
  • field names of the same name as the target file will be appended to the target file, if field names do not match they will be ignored in the output.

Authentication​

As will all Geoflip endpoints, include either your API Key or Authorization token in your request headers to properly authenticate. Refer to Authentication for more detailed explaination of how to authenticate to Geoflip.

General Structure of Append Requests​

All append endpoints follow a common structure, though the exact request format may vary by data type:

Endpoint Structure:​

Each append endpoint is structured as follows:

POST /v1/transform/{format}/append

  • format: This specifies the data format being used (e.g., geojson, shp, dxf, gpkg). As additional formats are supported, this naming convention will apply to them as well.

Request Format​

GeoJSON Append Requests​

Since GeoJSON data can be passed as a simple JSON payload, GeoJSON append requests require only a JSON body with two main keys:

  • append_geojson_list: Contains the new GeoJSON features to append.
  • target_geojson: Defines the existing dataset to which new features will be added.
Example GeoJSON Append Request Payload
{
  "append_geojson_list": [
    {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": {
            "type": "Point",
            "coordinates": [102.0, 0.5]
          },
          "properties": {"prop0": "value0"}
        }
      ]
    }
  ],
  "target_geojson": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [100.0, 0.0]
        },
        "properties": {"prop0": "value2"}
      }
    ]
  },
  "output_format": "geojson",
  "output_crs": "EPSG:4326"
}

Other Format Append Requests (e.g., SHP, DXF, GPKG)​

For formats that rely on files, such as Shapefiles or DXF, append requests use multipart form data. This format allows you to specify files directly and add a JSON configuration.

  • file part is the binary target file
  • files part is the list of binary files to be appened to the target file
  • config is a JSON part where you can define your required:
    • output_format: the output format can be one of GeoJSON, DXF, SHP, GPKG
    • output_crs: the output coordinate system can be any valid EPSG
    • transformations: your list of transformations, refer to transformations for more information
    • input_crs: the input crs of the target file. (only required for DXF)
    • append_crs_mapping: the crs of each of the append files, this should be a list of EPSG crs values (ie "EPSG:4326") or a single crs value that will be used for all append files
append multipart form example SHP
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>GeoFlip Append SHP Example</title>
  <script src="https://cdn.jsdelivr.net/npm/axios/dist/axios.min.js"></script>
</head>
<body>

<h2>GeoFlip SHP Append Request</h2>
<p>This form demonstrates how to make a multipart form-data request to append SHP files using the GeoFlip API.</p>

<form id="shpAppendForm">
  <!-- API Key Header -->
  <label for="apiKey">API Key:</label>
  <input type="text" id="apiKey" name="apiKey" placeholder="YOUR_API_KEY" required>
  <br><br>

  <!-- Target SHP File -->
  <label for="targetFile">Target SHP File:</label>
  <input type="file" id="targetFile" name="file" accept=".zip" required>
  <br><br>

  <!-- SHP Files to Append -->
  <label for="appendFiles">SHP Files to Append:</label>
  <input type="file" id="appendFiles" name="files" accept=".zip" multiple required>
  <br><br>

  <!-- JSON Configuration Part -->
  <label for="config">Configuration (JSON):</label>
  <textarea id="config" name="config" rows="5" cols="50" required>
{
  "output_format": "shp",
  "output_crs": "EPSG:4326"
}
  </textarea>
  <br><br>

  <!-- Submit Button -->
  <button type="submit">Submit Append Request</button>
</form>

<script>
  document.getElementById("shpAppendForm").addEventListener("submit", function(event) {
    event.preventDefault();

    const apiKey = document.getElementById("apiKey").value;
    const targetFile = document.getElementById("targetFile").files[0];
    const appendFiles = document.getElementById("appendFiles").files;
    const config = document.getElementById("config").value;

    const formData = new FormData();
    formData.append("file", targetFile);
    
    // Append multiple files to "files"
    for (let i = 0; i < appendFiles.length; i++) {
      formData.append("files", appendFiles[i]);
    }

    formData.append("config", config);

    axios.post("https://api.geoflip.io/v1/transform/shp/append", formData, {
      headers: {
        "apiKey": `${apiKey}`,
        "Content-Type": "multipart/form-data"
      },
      responseType: "blob" // This ensures Axios treats the response as a binary blob
    })
    .then(response => {
      // Handle the binary response as a file download
      const url = window.URL.createObjectURL(new Blob([response.data]));
      const link = document.createElement("a");
      link.href = url;

      // Set a default filename or obtain from response headers if available
      link.setAttribute("download", "output.shp");
      document.body.appendChild(link);
      link.click();
      document.body.removeChild(link);
    })
    .catch(error => {
      console.error("Error:", error);
      alert("There was an error processing the request. Check the console for details.");
    });
  });
</script>

</body>
</html>

Asynchronous Processing​

For larger files or operations that may require additional processing time, you can use asynchronous processing. To enable this, add async=true to your request URL, allowing the server to handle the request in the background and provide a task ID for tracking.

POST /v1/transform/{format}/append?async=true

Please refer to the async requests page for more information on how to use async geoflip requests.

Summary​

The append endpoints in GeoFlip offer an, extensible framework for adding data to existing spatial datasets across multiple formats. By following these principles, developers can easily integrate with any append endpoint as new formats are introduced.

This guide aims to be a flexible resource for future formats, which will adhere to these same principles and structures.