Skip to main content

Merge

GeoFlip’s merge endpoints allow developers to combine multiple spatial datasets into a single unified file, supporting all currently supported data formats like GeoJSON, Shapefile (SHP), DXF, and GeoPackage (GPKG). Unlike the append operation, the merge functionality does not preserve attribute data from the input files; it focuses solely on merging geometries.

Merge Illustration

Things to keep in mind when performing a merge:

  • All files must be of the same file format.
  • Mixed geometry types are supported: The input data does not need to have the same geometry type. If the output format requires geometry consistency (e.g., SHP), GeoFlip will generate a separate file for each geometry type (e.g., one for points, one for lines, and one for polygons).
  • If performing the append on data with no inherently defined CRS (ie DXF) you must provide crs information
    • If merging files without a predefined coordinate reference system (CRS) like DXF, you must specify the CRS for all input files using the input_crs_mapping parameter.
      • 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 merge files
  • Merged output will not contain any attribute data—only geometry is preserved.

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 Merge Requests​

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

Endpoint Structure:​

Each merge endpoint is structured as follows:

POST /v1/transform/{format}/merge

  • 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 Merge Requests​

For GeoJSON data, the merge request is handled via a simple JSON payload with the input_geojson_list key containing all datasets to merge.

  • input_geojson_list: Contains the new GeoJSON features to merge.
Example GeoJSON Merge Request Payload
{
  "input_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 Merge Requests (e.g., SHP, DXF, GPKG)​

For formats relying on files (like Shapefiles or DXF), merge requests use multipart form data. If the input data contains mixed geometry types and the output format is geometry strict (like SHP), separate files will be generated for each geometry type.

  • files part is the list of binary files to be merged
  • 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_mapping: the crs of each of the merge 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
merge multipart form example SHP
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>GeoFlip Merge SHP Example</title>
  <script src="https://cdn.jsdelivr.net/npm/axios/dist/axios.min.js"></script>
</head>
<body>

<h2>GeoFlip SHP Merge Request</h2>
<form id="shpMergeForm">
  <label for="apiKey">API Key:</label>
  <input type="text" id="apiKey" name="apiKey" placeholder="YOUR_API_KEY" required>
  <br><br>

  <label for="mergeFiles">SHP Files to Merge:</label>
  <input type="file" id="mergeFiles" name="files" accept=".zip" multiple required>
  <br><br>

  <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>

  <button type="submit">Submit Merge Request</button>
</form>

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

    const apiKey = document.getElementById("apiKey").value;
    const mergeFiles = document.getElementById("mergeFiles").files;
    const config = document.getElementById("config").value;

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

    formData.append("config", config);

    axios.post("https://api.geoflip.io/v1/transform/shp/merge", formData, {
      headers: {
        "apiKey": `${apiKey}`,
        "Content-Type": "multipart/form-data"
      },
      responseType: "blob"
    })
    .then(response => {
      const url = window.URL.createObjectURL(new Blob([response.data]));
      const link = document.createElement("a");
      link.href = url;
      link.setAttribute("download", "merged_output.zip");
      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 large merge operations, you can use asynchronous processing by adding async=true to your request URL, allowing the server to handle it in the background:

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

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

Summary​

The merge endpoints in GeoFlip provide a flexible way to combine multiple spatial datasets into one output while supporting mixed geometry types. For geometry strict formats, GeoFlip will generate separate outputs for each geometry type. By following these guidelines, developers can efficiently integrate the merge functionality into their applications.