Export query results

How to download item data

You can create an export task that uses an AQS query to fetch items, then export their data to a downloadable file.

For more information, see:

the Export endpoints on Swagger and ReDoc
the Task endpoints on Swagger and ReDoc

Example JavaScript

This is an example of an export task:

Specify an AQS query that fetches items of the Street Lighting Heads interface, returning their Unit Number, Installed Date and Geometry attributes.
Initiate an export in CSV file format.
Repeatedly check if the export task has completed.
After the task has completed, request a signed download URL for the exported file (valid for 24 hours) and output it to console.

// load a http request library
const axios = require('axios');

// enter your api key here!
const apiKey = '6582de5a-1c3d-4873-a07c-ce17e363823e';

// specify the AQS query that will fetch our item data
const aqs = {
  type: 'Query',
  properties: {
    // search within the Street Lighting Heads interface
    dodiCode: 'designInterfaces_streetLightingHeads',
    // return a subset of attributes, alternatively use "All" to get everything
    attributes: ['attributes_streetLightingUnitsUnitNumber', 'attributes_assetsInstalledDate', 'attributes_itemsGeometry'],
  },
};

// run the export
axios({
  method: 'POST',
  url: 'https://api.uk.alloyapp.io/api/export',
  headers: { Authorization: `Bearer ${apiKey}` },
  // specify the export model
  data: {
    aqs,
    // export as CSV
    discriminator: 'CsvExportWebRequestModel',
    // optional
    filename: 'myexport.csv',
    // optional: label attribute columns with their codes
    exportHeaderType: 'Codes',
    // optional: convert dates/times to company project's time zone, instead of UTC+00:00
    exportDateTimeAsLocalTime: true,
    // optional: reproject exported geometry from WGS84 (Longitude, Latitude) to British National Grid (EPSG:27700)
    proj4: '+proj=tmerc +lat_0=49 +lon_0=-2 +k=0.9996012717 +x_0=400000 +y_0=-100000 +ellps=airy +datum=OSGB36 +units=m +no_defs',
  },
})
  .then((response) => {
    console.log('export started with task id: ' + response.data.alloyTaskId);

    // start checking for task completion because it is asynchronous
    checkForTaskCompletion(response.data.alloyTaskId);
  })
  .catch((error) => {
    // output any error data to the console, or the error message if there was no response
    console.log(error.response ? error.response.data : error.message);
  });

// define a function to check for task completion
function checkForTaskCompletion(taskId) {
  setTimeout(async () => {
    try {
      // make the service call to get the task
      const task = await getTask(taskId);

      // switch based on the status of the task
      switch (task.status) {
        case 'Queued':
          console.log('task queued, waiting for task status to change');
          break;
        case 'Running':
          console.log('task running, waiting for task status to change');
          break;
        case 'Complete': {
          console.log('task completed! fetching file...');

          // now get the item id that was made by the export
          const fileItemId = await getExportFileItemId(taskId);

          // generate a signed url to download the file, valid for 24 hours and usable without an Authorization header
          const fileUrl = await getFileDownloadUrl(fileItemId);

          // output the file url to the console
          // if running in a browser the url will force the browser to download the file
          // you can also access the file stream to save it to disk or do further processing
          console.log('file url: ' + fileUrl);

          // the task succeeded so finish processing here
          return;
        }
        case 'Failed':
          console.log('task failed: ' + task.error.message);
          // the task failed so finish processing here
          return;
        default:
          console.log('unknown task status, waiting for task status to change...');
      }

      // if we reach here, we want to queue another task check
      checkForTaskCompletion(taskId);
    } catch (e) {
      // log error, there was a problem getting the task or file
      console.log(e.response ? e.response.data : e.message);
    }
  }, 2000);
}

// define a function to get a task by id
async function getTask(taskId) {
  // fetch the task by id
  const response = await axios({
    method: 'GET',
    url: `https://api.uk.alloyapp.io/api/task/${taskId}`,
    headers: { Authorization: `Bearer ${apiKey}` },
  });

  return response.data.task;
}

// define a function to get an exported file item by task id
async function getExportFileItemId(taskId) {
  // fetch the exported file item for the stated task id
  const response = await axios({
    method: 'GET',
    url: `https://api.uk.alloyapp.io/api/export/${taskId}/file`,
    headers: { Authorization: `Bearer ${apiKey}` },
  });

  return response.data.fileItemId;
}

// define a function to get a signed download url for a file item, valid for 24 hours
async function getFileDownloadUrl(fileItemId) {
  // generate a signed url - it contains an opaque token so it can be used without an Authorization header
  const response = await axios({
    method: 'GET',
    url: `https://api.uk.alloyapp.io/api/file/${fileItemId}/generate-signed-url`,
    headers: { Authorization: `Bearer ${apiKey}` },
  });

  return 'https://api.uk.alloyapp.io' + response.data.url;
}

How to download item data​

Example JavaScript​

How to download item data

Example JavaScript