Machine Search Criteria¶

The machine search is the most important aspect of the API.

One of the core parts of the machine search is the statistics search - this allows you to put a search to the API and get a breakdown of how the results of that search are constructed. Using this it's possible to quickly answer questions like:

In what regions does manufacturer X product equipment that complies to emission level Y?

For range A what engine manufacturers do manufacturer B offer?

The machine search then allows you to find the individual machines that satisfy those search criteria.

Common¶

To keep consistency all machines searches use a common set of search criteria.

Schema¶

{
  "query": "string",
  "model": "string",
  "regions": [ "string" ],
  "ranges": [ "string" ],
  "manufacturers": [ "string" ],
  "statuses": [ "string" ],
  "machineIds": [ 0 ],
  "variationIds": [ 0 ],
  "revisionIds": [ 0 ],
  "legacyMachineIds": [ 0 ],
  "emissionLevels": [ "string" ],
  "fuelTypes": [ "string" ],
  "features": [ "string" ],
  "attributes": [
    {
      "attributeId": 0,
      "values": [ "string" ],
      "valueRange": {
        "min": 0.0,
        "max": 0.0
      },
      "unitValueRange": {
        "unit": "string",
        "min": 0.0,
        "max": 0.0
      }
    }
  ]
}

Parameters¶

query - a free-text query.

This will search equipment by manufacturer + name ignoring non-alphanumeric characters - this is the same search as seen on the first page of the portals.

model - an exact model name.

This will find equipment with an exact model name.

regions - an array of region keys.

This will find equipment available within these regions, for example; searching for ['europe'] will return equipment listed as worldwide, EMEAR, europe, or any region within europe.

Criteria as inclusive - so searching for ['france','germany'] will return equipment available in france and/or germany, as opposed to equipment that is available in both france and germany

ranges - an array of range keys.

This will find equipment within the given ranges, this can also be used to find equipment within parent ranges - so for example searching ['construction'] will return equipment for all ranges under the construction range.

manufacturers - an array of manufacturer names.

This will find equipment for the given set of manufacturers.

statuses - an array of statuses.

Equipment can either be Current or Discontinued, to search for only current equipment search for ['Current'], for only discontinued equipment search for ['Discontinued].

machineIds - an array of machine ids.

Find equipment by machine ids - please not all other search criteria are still applied - If you search for machine id 1234 with 'statuses': ['Current'] the equipment will not be returned if it is discontinued!

variationIds - an array of variation ids.

Find equipment by variation ids - as with machineIds other criteria is still applied.

revisionIds - an array of revision ids.

Find equipment by revision ids - as with machineIds other criteria is still applied.

legacyMachineIds - an array of legacy machine ids.

Find equipment using machine ids from the older v7 APIs. This is provided to help with migration.

Legacy machine ids link to variations, not machines, and may match to multiple variations if your subscription cover multiple top-level regions.

As with machineIds other criteria is still applied.

emissionLevels - an array of emission levels.

Find equipment that complies to a selection of emission levels.

Equipment must comply to all the levels set - so for example searching for ['tier-4','stage-v'] will return only equipment that is both Tier 4 and Stage V as opposed to Tier 4 and/or Stage V.

fuelTypes - an array of fuel-type keys.

Find equipment that uses one of the the specified fuel-types.

This criteria is inclusive - so for example searching for ['diesel','electric'] will return equipment that is either diesel and/or electric, as opposed to diesel and electric.

features - an array of feature keys.

Find equipment based on feature tags.

This criteria is inclusive by default - so for example searching for ['hybrid','high-lift'] will return equipment that is either hybrid and/or high-lift. However a '+' can be added to the start of any feature keys to make them required, so ['+hybrid','high-lift'] will return equipment that is hybrid and high-lift.

attributes - an array of attribute criteria.

This can be used to find equipment with specific attribute values. There are three types of attribute value, so three different criteria; alphanumeric search, numeric search, unit search.

An alphanumeric search allows you to find equipment with specific values for an attribute, so for example if you wanted to find articulated dump trucks with a 6x6 transmission type you would use the following:

{
  "attributeId": 52,
  "values": [ "6 x 6" ]
}

For numeric attributes a minimum/maximum value can be set for an attribute, so for example to find all 4 cylinder articulated dump trucks you would call:

{
  "attributeId": 33,
  "valueRange": {
    "min": 4,
    "max": 4
  }
}

For measure attributes a unit must be supplied with a minimum/maximum value, so for example to find all articulated dump trucks with a net engine output between 500-600hp you would call:

{
  "attributeId": 45,
  "unitValueRange": {
    "unit": "hp",
    "min": 500,
    "max": 600
  }
}

Attribute criteria combine together to filter down the returned equipment with each added dimension.

Examples¶

The best way to see how the criteria can be used is to follow through some examples.

To find all current equipment for manufacturers ABC Co and XYZ Co, complying to Stage V, within Europe you could use the following criteria:

{
  "regions": ["europe"],
  "manufacturers": ["ABC Co","XYZ Co"],
  "statuses": ["Current"],
  "emissionLevels": ["stage-v"]
}

If you already knew variation ids 1234, 2345, 3456 and you simply wanted to fetch the data you could just call:

{
  "variationIds": [1234,2345,3456]
}

If you wanted to reduce that down to only the diesel equipment in that list you could then call:

{
  "variationIds": [1234,2345,3456],
  "fuelTypes": ["diesel"]
}

Statistics¶

Statistics criteria are used for when searching for equipment stats - they are are made up of the common criteria as well as a couple of additional options to control the amount of data returned.

Schema¶

{
  "include": [ "string" ],
  "includeAttributes": [ 0 ],
  ... common search criteria here
}

Parameters¶

include what stats results do you want?

The options are; Count, Manufacturers, Ranges, Regions, FuelTypes, Features, EmissionLevels, and AttributeValues. By default Count, Manufacturers, Ranges, and Regions are included.

includeAttributes an array of attribute ids to be included in the AttributesValues stats.

Tip

Deciding what to include is a balancing act - including more into one stats search will make the request take longer, as more work needs to be done.

Search¶

Search criteria is also made up of the common criteria as well as some additional options to control the amount of data returned and the ordering of that data.

Schema¶

{
  "level": "string",
  "attributeTags": [ "string" ],
  "includeMedia": false,
  "includeFormattedValues": false,
  "mediaTypes": [ "string" ],
  "orderBy": "string",
  "orderByAttribute": 0,
  "orderByAscending": true,
  ... common search criteria here
}

Parameters¶

level - The level of data to be returned machines/variations/revisions/attributes. As the levels imply each level adds more depth to the search results - this comes at the cost of slower query times and larger responses.
attributeTags - Where the level is set to attributes this can be used to reduce the attributes returned to only those with specific tags. For example most ranges will have 2-3 attributes tagged as highlight for use in search results; searching with "attributeTags": ["highlight"] will return only the values for these 2-3 attributes.
includeMedia - Should media be included in the output? False by default. This is only effective if the level is set to revisions.
includeFormattedValues - Should formatted values be included in the output? False by default. This is only effective if the level is set to attributes.
mediaTypes - Where includeMedia is true this can be used in a similar way as attributeTags to restrict the media that is returned. For example; searching with "mediaTypes": ["hero-shot"] will return only the hero shot images on equipment.
orderBy - Controls the order in which results are returned. Possible values are Attribute and ManufacturerModel, where set to Attribute orderByAttribute must be set too.
orderByAttribute - Where the orderBy is set to Attribute this is the attribute id by which to order.
orderByAscending - Should results be sorted in ascending or descending order? True by default.