Search for items

How to search for items

Searching for items within Alloy is one of the most frequent requests that you are likely to perform. This is accomplished by using an AQS query.

For more information, see the Aqs endpoints on Swagger and ReDoc.

Example JavaScript

This example demonstrates searching for a Street Lights item by its Unit Number attribute.

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

// enter your api key here!
const apiKey = 'e0e3a4ef-5ec8-4e05-ac25-a34adadf4a80';

// run the AQS (alloy query syntax) search
axios({
  method: 'POST',
  url: `https://api.uk.alloyapp.io/api/query`,
  headers: { Authorization: `Bearer ${apiKey}` },
  // specify the AQS model
  data: {
    // perform a Query type search
    type: 'Query',
    properties: {
      // search items of the Street Lights design
      dodiCode: 'designs_streetLights',
      // return a subset of attributes, alternatively use "All" to get everything
      // in this case, we're only interested in the unit number
      attributes: ['attributes_streetLightingUnitsUnitNumber'],
    },
    children: [
      {
        // the query performs an equality check
        type: 'Equals',
        children: [
          // the left side of the equality check is an attribute.
          // the attribute we want to search on is the unit number
          {
            type: 'Attribute',
            properties: {
              // specify the attribute code of the attribute to search on
              // must be an attribute on the dodiCode we chose to search in above
              attributeCode: 'attributes_streetLightingUnitsUnitNumber',
            },
          },
          // the right side of the equality check is a string.
          // this is the unit number you want to match on
          {
            type: 'String',
            properties: {
              // an array of string values to exact match on, passing multiple
              // unit numbers would return any that matched
              values: ['STL10009'],
            },
          },
        ],
      },
    ],
  },
})
  .then((response) => {
    // output the results to the console
    response.data.results.forEach((item) => {
      console.log(`item "${item.itemId}" found`);
    });
  })
  .catch((error) => {
    // output any error data to the console
    console.log(error.response.data);
  });