Skip to main content

Writers

Geoflip supports an expanding range of output data formats. Your requested output format can be defined in the output_format configuration setting, along with the output_crs setting to define the Coordinate Reference System (CRS) for the output data.

Depending on your requested output format, you will need to handle either a normal JSON response containing your output (ie GeoJSON) or you will need to handle a binary data payload.

GeoJSON Outputs​

GeoJSON output is useful for lightweight, web-friendly data sharing and visualization. To request GeoJSON output:

  • Set output_format to geojson: GeoJSON is natively supported in web applications and libraries like Leaflet and Mapbox.
  • Define output_crs: Specify the output CRS using an EPSG code (e.g., "EPSG:4326" for WGS84, which is common for web mapping).
  • Transformations (Optional): Apply transformations such as buffer, clip, union, or erase directly to GeoJSON data in the request payload. These transformations are ideal for lightweight processing directly within the API, saving time in data preparation.

Example payload for GeoJSON output:

{
  "input_geojson": { /* GeoJSON data */ },
  "output_format": "geojson",
  "output_crs": "EPSG:4326",
}

Binary Outputs (SHP, DXF, GPKG etc..)​

For applications requiring binary format outputs (e.g., SHP for GIS systems, DXF for CAD applications, or GPKG for geospatial databases), Geoflip supports these formats and returns a binary file as the response. Make sure your code is set up to correctly handle binary file responses.

Handling Binary File Responses​

When Geoflip returns a binary response (e.g., SHP, DXF, or GPKG file), your application should be prepared to process this binary data.

Here’s an example of the payload structure for converting GeoJSON input to a SHP output format with a specified CRS:

{
  "input_geojson": { /* GeoJSON data */ },
  "output_format": "shp",
  "output_crs": "EPSG:4326"
}

When making this request, Geoflip will return the processed file as a binary response. Here’s how to handle this response in JavaScript using Axios:

const axios = require('axios');

// Define your payload
const payload = {
  input_geojson: { /* GeoJSON data */ },
  output_format: "shp",
  output_crs: "EPSG:4326"
};

// Make the API call
axios.post(
  'https://api.geoflip.io/v1/transform/geojson',   // Geoflip API endpoint
  payload,                                         // Payload with input data and configuration
  {
    headers: {
      'Content-Type': 'application/json',
      'apiKey': 'YOUR_API_KEY'                     // Replace with your actual API key
    },
    responseType: 'blob'                            // Ensure response is received as a binary blob
  }
)
.then(response => {
  if (response.status === 200) {
    // Create a URL for the binary data
    const url = window.URL.createObjectURL(new Blob([response.data]));
    const link = document.createElement('a');
    link.href = url;

    // Set the download file name and simulate a click to download
    link.setAttribute('download', 'output.shp');  // Adjust extension if needed
    document.body.appendChild(link);
    link.click();

    // Clean up by removing the link element after the download
    document.body.removeChild(link);
    console.log("File downloaded successfully.");
  }
})
.catch(error => {
  console.error('Error during file download:', error);
});

Key Steps​

  1. Define the Payload: In this example we construct the payload to include "input_geojson", "output_format", and "output_crs", specifying the input data and desired output format.

  2. Set responseType to 'blob': Setting responseType to 'blob' ensures the response is received as binary data. This step is important for handling output file correctly, as it prevents Axios from interpreting the response as text.

  3. Handling the Binary File: In the example, we handle the binary response by generating a temporary download link, allowing users to download the file directly. This is just one way to handle the binary data. Alternatively, you could process it in other ways, such as:

    • Saving to Disk: Use file-saving functions to store the data on the server or client.
    • Direct Processing: Pass the binary data to a function or API for further processing.
    • Streaming: Stream the data to another application or workflow.

  4. Optional Cleanup: If creating a temporary link for a download, clean up afterward by removing any temporary elements to keep the DOM uncluttered.

This approach allows flexibility in handling the response, whether you need to download, store, or process the file in your own way.

A note on Geoflip Async requests​

Geoflip also supports async geoprocessing requests on all routes, allowing your data to be processed asynchronously. Instead of processing your data and responding immediately with the result directly, Geoflip returns a JSON payload containing a task_id.

You can use this task_id to check the status of your job. Once the job is complete, Geoflip will provide a URL that you can use to download the resulting binary or GeoJSON data.

Async requests are best used when data is large and processing takes more than a few seconds to respond.

Read more about making async requests here.

Performing Reprojections​

The Geoflip API inherently supports reprojecting data from one coordinate system to another by specifying an output_crs. When you define an output_crs, Geoflip determines the input data's current projection by either:

  • Reading it directly from the data: Some formats, like SHP and GPKG, contain embedded CRS information that Geoflip can detect automatically.

  • Requiring an input_crs: In cases where the input format doesn’t include CRS information (such as DXF), you’ll need to provide an input_crs to specify the coordinate system of the incoming data.

  • Assuming the CRS: For formats like GeoJSON, Geoflip assumes a default CRS if none is specified. For example, GeoJSON defaults to WGS84 (EPSG:4326) according to the GeoJSON specification.

By defining output_crs, Geoflip reprojects the input data from its detected or provided CRS to the desired output coordinate system using a

Geoflip supports accurate global transformations between coordinate systems by automatically applying the most suitable transformation method based on the input and output CRSs. Where relevant, Geoflip utilizes precise grid-based transformations to account for regional datum shifts, ensuring high accuracy for localized data. For other projections, Geoflip applies standard transformation techniques to convert data seamlessly, providing reliable reprojected outputs for diverse global applications without additional configuration required by the user.