Skip to main content

File uploads and jobs

uploadGeofences​

uploadGeofences imports a geofence file and waits for the import job to finish. It requests a presigned upload URL, uploads the file, finalizes the upload, starts the import job, and polls until the job reaches a terminal status.

import {SpatialFlow, uploadGeofences} from '@spatialflow/sdk';

const client = new SpatialFlow({apiKey: process.env.SPATIALFLOW_API_KEY});

const result = await uploadGeofences({
client,
filePath: 'boundaries.geojson',
groupName: 'regions',
timeout: 120_000,
onStatus: (status) => console.log(`Status: ${status}`),
});

console.log(`Created ${result.createdCount}, failed ${result.failedCount}`);
for (const geofence of result.createdGeofences) {
console.log(geofence.id, geofence.name);
}
for (const failure of result.errors) {
console.log(failure.index, failure.name, failure.error);
}

Options​

OptionTypeDefaultDescription
clientSpatialFlowrequiredThe client to use
filePathstringrequiredPath to a .geojson, .json, .kml, or .gpx file
groupNamestringnoneGroup name for the created geofences
timeoutnumber300000Polling deadline in milliseconds (see pollJob)
pollIntervalnumber2000Time between status polls, in milliseconds
onStatus(status, response) => voidnoneCalled after each poll

An API key needs geofences:create, geofences:read, and storage:write, and its owner must be an owner or manager. The helper reads the whole file into memory and uses the global fetch, so it needs Node.js 18 or later.

Result​

uploadGeofences resolves to a JobResult:

FieldTypeDescription
jobIdstringImport job ID
statusstringFinal status
createdCountnumberGeofences created
failedCountnumberFeatures that failed
totalFeaturesnumberFeatures in the file
createdGeofences{id, name}[]The geofences that were created
errors{index, name, error}[]Per-feature failures
warningsstring[]Warnings from processing
durationnumber | undefinedDuration in seconds, when reported
resultsRecord<string, unknown>The raw results object
rawResponseunknownThe last status response

pollJob​

pollJob polls any job-status call until the status is completed or failed. uploadGeofences uses it for the import job.

import {SpatialFlow, pollJob, JobFailedError, JobTimeoutError} from '@spatialflow/sdk';

const client = new SpatialFlow({apiKey: process.env.SPATIALFLOW_API_KEY});
const jobId = '3f1b6a52-0000-0000-0000-000000000000';

try {
const result = await pollJob({
fetchStatus: () => client.geofences.appsGeofencesApiGetUploadJobStatus(jobId),
timeout: 120_000,
pollInterval: 2000,
onStatus: (status) => console.log(`Status: ${status}`),
});
console.log(`Created ${result.createdCount} geofences`);
} catch (error) {
if (error instanceof JobFailedError) {
console.log(`Job ${error.jobId} failed: ${error.errorMessage}`);
} else if (error instanceof JobTimeoutError) {
console.log(`Gave up after ${error.timeoutMs} ms, last status ${error.lastStatus}`);
} else {
throw error;
}
}

Options​

OptionTypeDefaultDescription
fetchStatus(signal: AbortSignal) => Promise<T>requiredFetches the current job status. The signal aborts at the deadline
timeoutnumber300000Wall-clock deadline in milliseconds, status calls included
pollIntervalnumber2000Time between polls, in milliseconds
terminalStatusesstring[]['completed', 'failed']Statuses that end polling
onStatus(status, response) => voidnoneCalled after each poll
extractJobId(response) => stringreads job_idCustom job ID lookup
extractStatus(response) => stringreads statusCustom status lookup

A job with status failed rejects with JobFailedError, which has jobId, errorMessage, and results. The timeout is a wall-clock deadline. Time spent in status calls counts, and the wait between polls is cut short at the deadline. A status call still running then is aborted through its signal, and pollJob rejects without waiting for it. The rejection is a JobTimeoutError, which extends TimeoutError and has jobId, timeoutMs, and lastStatus. Pass the signal on to the request, as fetchStatus: (signal) => client.geofences.appsGeofencesApiGetUploadJobStatus(jobId, {signal}) does, so the request stops too.