ETL API reference (v1)

Endpoints

Get all products

Get all products listed on the ETL. The response is paginated.

By default products are sorted by the date they were added to the ETL, with the most recent first.

Path

/api/v1/products

Parameters

Name	Type	Description
listingStatus Optional, in query string	string	The listing status of the product. By default only currently listed products are shown. Possible values: current currentOrRemoved removed
page Optional, in query string	integer	The page number you want to retrieve.
size Optional, in query string	integer	The number of records per page, up to a maximum of 200.
sort Optional, in query string	string	The sorting criteria of the results, in the format: propertyName(,asc|desc) e.g. sort=name or sort=dateAdded,desc. Default sort order is ascending. Multiple sort criteria are supported.

Response

Returns a PagedProductList

Search products by field text

Search for products by the text value of certain fields. For example, get all products manufactured by 'Acme Inc', or with the model number 'XYZ123'.

Search terms do not need to be exact. The search engine will return products that best match the given terms.

For example, a search for products in the 'hand dryers' technology will still match products even though the full technology name is 'high speed hand air dryers'.

Parameters can be combined to return only products which match on all criteria.

By default, the results are ordered by relevance to the search parameters. This can be changed with the sort parameter.

Path

/api/v1/products/search/byFieldText

Parameters

Name	Type	Description
listingStatus Optional, in query string	string	The listing status of the product. By default only currently listed products are shown. Possible values: current currentOrRemoved removed
manufacturer Optional, in query string	string	The name of the product manufacturer.
modelNumber Optional, in query string	string	The product model number.
page Optional, in query string	integer	The page number you want to retrieve.
productName Optional, in query string	string	The product name.
size Optional, in query string	integer	The number of records per page, up to a maximum of 200.
sort Optional, in query string	string	Sorting criteria in the format: propertyName(,asc|desc) e.g. sort=name or sort=dateAdded,desc. Default sort order is ascending. Sorting on multiple properties is not supported.
subTechnology Optional, in query string	string	The name of the sub-technology category.
technology Optional, in query string	string	The name of the technology category.
uniclass Optional, in query string	string	The Uniclass classification code the product has been categorised into.

Response

Returns a PagedProductList

Get multiple products

Get products by their IDs. Multiple IDs can be specified by repeating the query parameter. This allows multiple products to be fetched in a single request.

Path

/api/v1/products/search/byIds

Parameters

Name	Type	Description
productId Required, in query string	integer	The ID of the product you want to retrieve.

Response

Returns a ProductList

Get a specific product

Get a specific product by its ID.

Path

/api/v1/products/{productId}

Parameters

Name	Type	Description
productId Required, in path	integer	The ID of the product you want to retrieve.

Response

Returns a Product

Search for products, technologies and sub-technologies

Search across the ETL for products, technology categories and sub-technology categories using a free text search term. Filters can also be applied to limit the returned results to only products matching the specified restrictions.

The same filter parameter can be specified multiple times, in which case they are logically ORed, meaning products matching any of the provided filters will be returned.

Multiple different filter parameters can also be specified, in which case they are logically ANDed, meaning products must match all of provided different filters.

For example ?manufacturer=1&manufacturer=2&technology=3&technology=4 will return all products produced by manufacturer ID 1 or 2 and which are in technology categories with ID 3 or 4.

Products can also be filtered by their technical characteristics using the feature definition filter parameter.

By default, the results are ordered by relevance to the search parameters. This can be changed with the sort parameter.

Path

/api/v1/search

Parameters

Name	Type	Description
feature<FeatureDefinitionId> Optional, in query string	string	A feature filter. The name of this parameter includes the feature definition ID you want to filter on. The parameter value can either be an exact value, or a range of values. To specify that a product must have an exact value for a feature, the value can be provided as the parameter value directly. For example, assuming the feature 'Total energy consumption in kW' for a certain technology category has an feature definition ID of 12-5, to find all products with a total energy consumption of 1.3 kw use ?feature12-5=1.3 Similarly for TEXT or ENUM type features the required feature value can be used as the parameter value. For example, assuming an ENUM feature 'Fuel type' with an ID of 8-1, to find all products with a with a fuel type of 'Gas' use ?feature8-1=Gas For numeric features a range of values can also be specified using the parameter value minXmaxY where X is the minimum value and Y is the maximum value. For example, assuming the feature 'Total energy consumption in kW' for a certain technology category has an feature definition ID of 12-5, to find all products with a total energy consumption of between 0.5 and 2kw (inclusive) use ?feature12-5=min0.5max2
keywords Optional, in query string	string	The search term. Can be multiple words. These terms will be matched against all technology, sub-technology and product data.
listingStatus Optional, in query string	string	The listing status of the product. By default only currently listed products are shown. Possible values: current currentOrRemoved removed
manufacturer Optional, in query string	integer	A manufacturer ID. Only products produced by this manufacturer will be returned.
page Optional, in query string	integer	The page number you want to retrieve.
size Optional, in query string	integer	The number of records per page, up to a maximum of 200.
sort Optional, in query string	string	Sorting criteria of the resulting products in the format: propertyName(,asc|desc) e.g. sort=name or sort=dateAdded,desc. Default sort order is ascending. Sorting on multiple properties is not supported.
subTechnology Optional, in query string	integer	A sub-technology ID. Only products in this sub-technology category will be returned.
technology Optional, in query string	integer	A technology ID. Only products in this technology category will be returned.
uniclass Optional, in query string	string	A Uniclass classification code. Only products that have been categorised under this code will be returned.

Response

Returns a SearchResult

Get all sub-technologies

Get all the sub-technology categories and their feature definitions on the ETL.

Path

/api/v1/subTechnologies

Response

Returns a SubTechnologyList

Get a specific sub-technology

Get a specific sub-technology and its feature definitions by ID.

Path

/api/v1/subTechnologies/{subTechnologyId}

Parameters

Name	Type	Description
subTechnologyId Required, in path	integer	The ID of the sub-technology you want to retrieve.

Response

Returns a SubTechnology

Get all products in a specific sub-technology

Get all products listed on the ETL under the given sub-technology. The response is paginated.

By default products are sorted by the date they were added to the ETL, with the most recent first.

Path

/api/v1/subTechnologies/{subTechnologyId}/products

Parameters

Name	Type	Description
listingStatus Optional, in query string	string	The listing status of the product. By default only currently listed products are shown. Possible values: current currentOrRemoved removed
page Optional, in query string	integer	The page number you want to retrieve.
size Optional, in query string	integer	The number of records per page, up to a maximum of 200.
sort Optional, in query string	string	The sorting criteria of the results, in the format: propertyName(,asc|desc) e.g. sort=name or sort=dateAdded,desc. Default sort order is ascending. Multiple sort criteria are supported.
subTechnologyId Required, in path	integer	The ID of the sub technology whose products you want to retrieve

Response

Returns a PagedProductList

Get all technologies

Get all the technology categories and their feature definitions on the ETL.

Path

/api/v1/technologies

Response

Returns a TechnologyList

Get a specific technology

Get a specific technology and its feature definitions by ID.

Path

/api/v1/technologies/{technologyId}

Parameters

Name	Type	Description
technologyId Required, in path	integer	The ID of the technology you want to retrieve.

Response

Returns a Technology

Get all products in a specific technology

Get all products listed on the ETL under the given technology. The response is paginated.

By default products are sorted by the date they were added to the ETL, with the most recent first.

Path

/api/v1/technologies/{technologyId}/products

Parameters

Name	Type	Description
listingStatus Optional, in query string	string	The listing status of the product. By default only currently listed products are shown. Possible values: current currentOrRemoved removed
page Optional, in query string	integer	The page number you want to retrieve.
size Optional, in query string	integer	The number of records per page, up to a maximum of 200.
sort Optional, in query string	string	The sorting criteria of the results, in the format: propertyName(,asc|desc) e.g. sort=name or sort=dateAdded,desc. Default sort order is ascending. Multiple sort criteria are supported.
technologyId Required, in path	integer	The ID of the technology whose products you want to retrieve.

Response

Returns a PagedProductList

Response types

FeatureDefinition

A feature definition represents a technical characteristic of a product, such as energy efficiency or power rating. A product will have its value for this characteristic recorded in a ProductFeature.
Each technology and sub-technology category has a predefined list of feature definitions that products listed in those categories will have corresponding ProductFeature values for.
Some products may not have corresponding ProductFeature values for all the feature definitions in a technology/sub-technology category, as the product may have been added to the ETL before some of the technical characteristics were captured as part of the product application process.

Name	Type	Description
displayOrder	integer	The order in which this feature definition is displayed against a product. This will be null if no specific order has been specified.
enumOptions	Array of FeatureEnumOptions	The possible values for this feature if it is of an enumerated type. This will be an empty array if the feature definition type is not ENUM.
featureId	string	The ID of this feature definition.
filterDisplayOrder	integer	The display order of this feature within the ETL browse products page filter section. This will be null if isFilterable is false.
isActive	boolean	If false, data for this feature is no longer collected for new products but will still be shown for existing products where available.
isFilterable	boolean	True if this feature is filterable on the ETL browse products page filter section. If this is false you can still filter on this feature in this API.
isSortable	boolean	True if this feature is sortable on the ETL browse products page sort dropdown. If this is false you can still sort by this feature in this API.
maxValue	number	The maximum value this feature has across all products which have a corresponding ProductFeature. This will be null if type is not a numeric type.
minValue	number	The minimum value this feature has across all products which have a corresponding ProductFeature. This will be null if type is not a numeric type.
name	string	The name of this feature definition.
sortDisplayOrder	integer	The display order of this feature within the ETL browse products page sort dropdown. This will be null if isSortable is false.
type	string	The data type of this feature definition. Possible values: DOUBLE ENUM INTEGER RATIO TEXT
unit	string	The unit of the feature definition, such as kW, mm, %. This will be null if the value has no unit, for example if the type is ENUM.

FeatureEnumOption

A possible option for an enumerated FeatureDefinition.

Name	Type	Description
displayOrder	integer	The order this option should be displayed in.
option	string	The value of this option.

IndoorUnit

An indoor unit for a heating, ventilation and air conditioning (HVAC) system.

Name	Type	Description
capacity	number	The capacity of this indoor unit in litres.
modelNumber	string	The model number of this indoor unit.

Manufacturer

A manufacturer of a product or products.

Name	Type	Description
address	string	The address of this manufacturer, excluding postcode. This may be null if it was not provided.
country	string	The country the address of the manufacturer is based in. This may be null if it was not provided.
emailAddress	string	The email address of this manufacturer. This may be null if it was not provided.
id	integer	The ID of this manufacturer.
name	string	The name of this manufacturer.
postcode	string	The postcode of this manufacturer. This may be null if it was not provided.
telNumber	string	The telephone number of this manufacturer. This may be null if it was not provided.
website	string	The website of this manufacturer. This may be null if it was not provided.

NestedSubTechnology

An alternate simpler representation of a sub-technology. Used when returning the full sub-technology model would not be practical.

Name	Type	Description
dateRemoved	string	The date this sub-technology was removed from the ETL. This will be null if isRemoved is false.
id	integer	The sub-technology ID.
isRemoved	boolean	The removal status of this sub-technology. If true, this sub-technology has been removed from the ETL.
isUnlisted	boolean	If true, products in this sub-technology category are not individually listed.
name	string	The sub-technology name as it appears on the ETL.
subTechnologyInformationUrl	string	A link to more information about this sub-technology on the ETL.
urlSlug	string	A URL safe string that uniquely identifies this sub-technology.

NestedTechnology

An alternate simpler representation of a technology. Used when returning the full technology model would not be practical.

Name	Type	Description
dateRemoved	string	The date this technology was removed from the ETL. This will be null if isRemoved is false.
id	integer	The technology ID.
isRemoved	boolean	The removal status of this technology. If true, this technology has been removed from the ETL and no longer has any product listed against it.
isUnlisted	boolean	If true, products in this technology category are not individually listed.
name	string	The technology name as it appears on the ETL.
nameSynonyms	Array of strings	A list of alternate names this technology may be known by.
technologyInformationUrl	string	A link to more information about the technology on the ETL.
urlSlug	string	A URL safe string that uniquely identifies this technology.

PagedProductList

A paginated list of products.

Name	Type	Description
page	ResultPage
products	Array of Products	The list of products.

Product

An ETL product. A product has a list of features which define its technical characteristics. A product may be removed from the current ETL if it no longer meets criteria or is not longer manufactured.

Name	Type	Description
dateAdded	string	The date this product was added to the ETL.
dateRemoved	string	The date this product was removed from the ETL. This will be null if isRemoved is false.
features	Array of ProductFeatures	A list of this product's features.
id	integer	The unique product ID
images	Array of ProductImages	A list of images of this product.
indoorUnits	Array of IndoorUnits	A list of compatible indoor units for this product (if applicable).
isRemoved	boolean	The removal status of this product. If true, this product has been removed from the ETL and is not longer listed.
manufacturer	Manufacturer
modelNumber	string	The model number of this product. This will be null if the product has no model number.
name	string	The name of this product
subTechnologyId	integer	The optional sub-technology category this product belongs to. This will be null if this product is not part of a sub-technology category.
technologyId	integer	The technology category this product belongs to.
uniclassCodes	Array of UniclassCodes	A list of Uniclass classification codes this product has been categorised into.

ProductFeature

A product specific value for a feature definition.

Name	Type	Description
displayOrder	integer	The order in which this feature is displayed against the product. This will be null if no specific order has been specified.
featureDefinitionId	string	The ID of the feature definition this feature relates to.
name	string	The name of this product feature.
numericValue	number	The numeric value of this product feature. This will be null if the value is not numeric (e.g. text).
unit	string	The unit of the product feature, such as kW, mm, %. This will be null if the value has no unit.
value	string	The value of this product feature, as a string.

ProductImage

A link to a product image.

Name	Type	Description
displayOrder	integer	The order in which this image is displayed against the product.
fileId	string	The image file ID.
url	string	A URL for the image. By default the image will be 200 pixels wide with a proportional height. This can be changed using the first part of the URL path. For example https://hostname/320x/image-id would return the image with a width of 320 pixels and a proportional height.

ProductList

A list of products.

Name	Type	Description
products	Array of Products	The list of products.

ResultPage

Pagination information associated with a response.

Name	Type	Description
number	integer	The number of items (e.g. products) in this page.
size	integer	The maximum size of the page.
totalElements	integer	The total number of items (e.g. products) available across all pages.
totalPages	integer	The total number of available pages.

SearchResult

A result of a search operation. Contains matching technologies, sub-technologies and products.

Name	Type	Description
implicatedSubTechnologyIds	Array of integers	A distinct list of sub-technology IDs products returned from the search belong to.
implicatedTechnologyIds	Array of integers	A distinct list of technology IDs products returned from the search belong to.
matchedProducts	PagedProductList
subTechnologies	Array of NestedSubTechnologys	The list of sub-technologies returned from the search.
technologies	Array of NestedTechnologys	The list of technologies returned from the search.

SubTechnology

An ETL sub-technology category. This provides further categorisation within a broader technology category.

Name	Type	Description
dateRemoved	string	The date this sub-technology was removed from the ETL. This will be null if isRemoved is false.
featureDefinitions	Array of FeatureDefinitions	A list of all feature definitions available in this sub-technology.
id	integer	The sub-technology ID.
isRemoved	boolean	The removal status of this sub-technology. If true, this sub-technology has been removed from the ETL and no longer has any product listed against it.
isUnlisted	boolean	If true, products in this sub-technology category are not individually listed.
name	string	The sub-technology name as it appears on the ETL.
parentTechnologyId	integer	The ID of this sub-technology's parent technology.
parentTechnologyInformationUrl	string	A link to more information about this sub-technology's parent technology on the ETL.
parentTechnologyName	string	The name of this sub-technology's parent technology as it appears on the ETL.
subTechnologyInformationUrl	string	A link to more information about this sub-technology on the ETL.
subTechnologyManufacturers	Array of Manufacturers	A list of all manufacturers who produce products in this sub-technology.
uniclassCodes	Array of UniclassCodes	A list of Uniclass codes which are applicable to products in this sub-technology.
urlSlug	string	A URL safe string that uniquely identifies this sub-technology.

SubTechnologyList

A list of sub-technologies.

Name	Type	Description
subTechnologies	Array of SubTechnologys	The list of sub-technologies.

Technology

An ETL technology category. All products on the ETL are listed under a specific technology category. A technology category may also contain further sub-technology categories within it.

Name	Type	Description
dateRemoved	string	The date this technology was removed from the ETL. This will be null if isRemoved is false.
featureDefinitions	Array of FeatureDefinitions	A list of all feature definitions available in this technology and any sub-technologies.
id	integer	The technology ID.
isRemoved	boolean	The removal status of this technology. If true, this technology has been removed from the ETL and no longer has any product listed against it.
isUnlisted	boolean	If true, products in this technology category are not individually listed.
name	string	The technology name as it appears on the ETL.
nameSynonyms	Array of strings	A list of alternate names this technology may be known by.
subTechnologies	Array of NestedSubTechnologys	A list of sub-technologies under this technology. This will be an empty array if this technology has no sub-technologies.
technologyInformationUrl	string	A link to more information about this technology on the ETL.
technologyManufacturers	Array of Manufacturers	A list of all manufacturers who produce products in this technology and any sub-technologies.
uniclassCodes	Array of UniclassCodes	A list of Uniclass codes which are applicable to products in this technology.
urlSlug	string	A URL safe string that uniquely identifies this technology.

TechnologyList

A list of technologies.

Name	Type	Description
technologies	Array of Technologys	The list of technologies.

UniclassCode

A Uniclass classification code. For more information see https://www.thenbs.com/our-tools/uniclass-2015

Name	Type	Description
classification	string	The Uniclass title.
code	string	The Uniclass code.