Upload Plots

The /upload_plots API endpoint allows users to upload data to cloud environments for processing.

It is the step following staging, and is required to make the data available for batch processing.

Uploading data via Dashboard

Uploading data is the second step to uploading data via the dashboard can be done through the Monitoring pane.

This step may take a few seconds to a few minutes depending on the data size, but will ultimately provide a success message if the upload was successful.

The uploaded data can then be consulted in the dashboard through the Suppliers pane.

Uploading data using the API

Parameters and Headers

An example of a payload for the /upload_plots endpoint is the following:

request_data = {
    "filename": "<collection_id_from_stage_plots>",
}

With the headers being:

headers = {
    'Authorization': "Bearer <authorization_token>",
    'Content-Type': 'application/json'
}

The Authorization header must be replaced by your user token. Check this page for more information on how to authenticate.

Python

In python, you can submit a request in the following way:

import requests
import json

response = requests.post("https://epoch-sco2-api.com/upload_plots", 
                         json=request_data, 
                         headers=headers)

json_result = json.loads(response.content)
print(json_result)

Javascript

const axios = require('axios');

const request_data = {
    "filename": "<collection_id_or_collection_name_from_stage_plots>",
};

const headers = {
    'Authorization': "Bearer <authorization_token>",
    'Content-Type': 'application/json'
};

axios.post("https://epoch-sco2-api.com/upload_plots", request_data, { headers })
    .then(response => {
        console.log(response.data);
    })
    .catch(error => {
        console.error(error);
    });

Curl

curl -X POST "https://epoch-sco2-api.com/upload_plots" \
-H "Authorization: Bearer <authorization_token>" \
-H "Content-Type: application/json" \
-d '{"filename": "<collection_id_from_stage_plots>"}'

Response

The response looks like this:

response = {
    "bq_task_id": 'W2GLGAD4TK7LJHPJ4VR6ECLX', # Task ID of the upload task
    "ee_task_id": 'JETBQ7F7WOBOARKVIU6PUM66', # Task ID of the upload task for earth engine
}

Geometry handling

Upload resolves every submitted row to a geometry it can assess, and returns one row out for every row in.

Plots supplied as a polygon

The supplied outline is authoritative and is stored as given, beyond a validity repair. AREA is computed from it, in hectares.

Plots supplied as a point

A point carries a location but no extent, so one is resolved for it from satellite imagery: the outline of the parcel the point falls in, grown outward from that point and capped by the row's own declared AREA. The result follows real field boundaries rather than an arbitrary shape centred on the coordinate.

Your declared AREA is preserved exactly as submitted. Only the shape is resolved, so the value you attested to is the value that is stored.

Where no parcel can be resolved at the point, the row falls back to a square of the declared area centred on it, and processing continues.

Overlapping parcels

Resolved outlines are made mutually disjoint before they are stored, so no two plots in an upload claim the same ground.

Coordinate precision

Coordinates are stored at six decimal places, about 0.11 m at the equator. A ring narrower than that in any direction cannot be represented as a polygon at this precision. Such a row is kept and stored at its location as a point rather than being discarded, so it still appears in your collection and in every row count.

Rows that carry no usable geometry

A row whose geometry is absent, empty, or cannot be resolved is still returned, with a null geometry and a cleanup_dropped value describing why. Row counts therefore reconcile against what you submitted, and a row is never silently absent from a result.