Lighting Facts REST API Documentation

The REST API allows developers to interact with the products list by sending an HTTP request. You can use any HTTP client in any programming language to interact with the API.

Base URL

All URLs referenced in the documentation have the following base:

https://www.lightingfacts.com/api/product

Request Format

For POST and PUT requests, the request body must be JSON, with the `Content-Type` header set to `application/json`.

Response Format

The response format for all requests is a JSON object. Whether a request succeeded or failed is indicated by the HTTP status code. A 2xx status code indicates success, whereas a 4xx status code indicates failure.

Product Data

This section provide details about the basic structure of a product along with the properties that define the attributes of that product.

Basic Format

Storing data through the Lighting Facts REST API is built around a JSON encoding of the object's data. The object is a basic representation of a product. The properties of this object represent the attributes of a product that provide information about a product. The values of these properties are bound by different validations.

For example, if you want to add a new product, your product object could contain:

{ 
    ModelNumber:    'Test Model Number',
    Brand:          'Test Brand Name',
    Description:    'Test Description'
}

Properties of a Product

SSL LightingFacts Listing Data
SSLProductID integer

The ID of the product

BaseProductID integer

The ID of the original product

ReplacesProductID integer

The BaseProductID of the product that is replaced by the current product

ReplacedByProductID integer

The BaseProductID of the product that replaces the current product

IsParent boolean

If the product is a single product or part of a product family

ParentID integer

The ID of the product that acts as a parent to the current product. This only applies to child products in the product family (0 if not a parent product).

Product Identity
OrganizationID integer

The ID of the organization manufacturing the product

Brand string

The name of the brand to which the product is associated.

ModelNumber string

The unique identifier that describe the model number of the product

ProductType integer

The ID of the type of the product

ProductCategory integer

The ID of the category of the product

UseLocation array of integers

A list of multiple use locations of the product

MountingBase array of integers

A list of multiple mounting base of the product

SubCategory array of integers

A list of multiple subcategories of the product

ProductSize integer

Size of the product

Lens integer

The lens of the product

Driver integer

The driver of the product

Wiring integer

The wiring of the product

Description string

A brief overview of the product

SKU string

A SKU of the product

ProductAvailabilityID integer

A ID of the availability status of the product

DLCSubmission boolean

Determines whether the product is being submitted for DLC qualification

NGLSubmission boolean

Determines whether the product is being submitted for Next Generation Luminaires competition

EnergyStar boolean

Determines whether the product is ENERGY STAR certified

DLCQualified boolean

Determines whether the product is DLC qualified

NextGenerationLuminaireWinner boolean

Determines whether the product is Next Generation Luminaire Competition Winner

Color Characteristics
TestedColorAccuracy number

Tested Color Accuracy (CRI) of the product

ColorAccuracy number

Color Accuracy (CRI) of the product

TestedLightColor number

Tested Light Color (CCT) of the product

LightColor number

Light Color (CCT) of the product

Duv number

DUV of the product

R9 number

R9 of the product

Duv number

DUV of the product

R9 number

R9 of the product

ColorCoordinateX number

X Color Coordinate of a product

ColorCoordinateY number

Y Color Coordinate of a product

ColorCoordinateU number

U Color Coordinate of a product

ColorCoordinateV number

V Color Coordinate of a product

ColorCoordinateUPrime number

U' Color Coordinate of a product

ColorCoordinateVPrime number

V' Color Coordinate of a product

IsTM30Public boolean

Set True to allow the submitted TM-30 file for this be product publically available on LightingFacts.com

Rf number

Rf value of this product generated from a TM-30 calculator

Rg number

Rg value of this product generated from a TM-30 calculator

IsColorTunable boolean

Indicates if the Product has color tuning capabilities

ColorTuningTypeID integer

The type of color tuning capabilities of a Product

Light Distribution
TestedLightOutput number

Tested Light Output of the product

LightOutput number

Light Output of the product

ZLD_0_60 number

Zonal Lumen Density (0-60°) of the product

ZLD_60_90 number

Zonal lumen density (60-90°) of the product

ZLD_90_120 number

Zonal lumen density (90-120°) of the product

ZLD_120_180 number

Zonal lumen density (120-180°) of the product

BeamAngle number

The average beam angle between Horizontal Beam Angle and Vertical Beam Angle

HorizontalBeamAngle number

Horizontal Beam Angle of the Product

VerticalBeamAngle number

Vertical Beam Angle of the Product

CenterBeamCandlePower number

Center Beam CandlePower of the product

SpacingCriteria_0_180 number

Spacing Criteria (0-180) of the product

SpacingCriteria_90_270 number

Spacing Criteria (90-270) of the product

Backlight number

Backlight of the product, based on BUG ratings

Uplight number

Uplight of the product, based on BUG ratings

Glare number

Glare of the product, based on BUG ratings

Electrical
TestedWatts number

Tested watts of the product

Watts number

Watts of the product

TestedLumensPerWatt number

Tested efficacy of the product

LumensPerWatt number

Efficacy of the product

PowerACDC number

Power Type of the product

PowerFactor number

Power Factor of the product

Frequency number

Frequency

THD number

Total harmonic distortion of the product

FlickerIndex number

Filcker index of the product

FlickerFundamentalFrequency number

Fundamental frequency of the product

FlickerFullOutputPercentage number

Full output of flicker as a percentage

FlickerFullOutputFrequency number

Frequency of full output of flicker

FlickerMinOutputPercentage number

Min output of flicker as a percentage

FlickerMinOutputFrequency number

Frequency at minimum output of flicker

DriverManufacturer string

Name of the driver manufacturer

DriverModelNumber string

Driver model number

DriverTypeID integer

Driver Type Id

Controls
IsDimmable boolean

True if the product has dimming capabilities

DimmingTypeID integer

The type ID that describes the product's dimmming capabilities. Only applicable if IsDimmable is set to true

DimmingCurveID integer

The type ID that describes the product's dimming curve. Only applicable if IsDimmable is set to true

HasDimmingInfo boolean

True if the submission includes a link to a dimming information page for the product.

DimmingInformationURL string

A valid url to page with manufacturer-provided dimming information. Required if HasDimmingInfo is set to true

DimmingMin integer

Minimum dimming output percentage. Only applicable if HasDimmingInfo is set to true

DimmingMax integer

Maximum dimming output percentage. Only applicable if HasDimmingInfo is set to true

DigitalCommunicationsProtocolID integer

The Dimming Communications Protocol ID

LuminairesOnControllerMin number

Minimum amount of luminaires on the controller

LuminairesOnControllerMax number

Maximum amount of luminaires on the controller

SpacingWidth number

Luminaire spacing width on the controller

SpacingLength number

Luminaire spacing length on the controller

Lumen Maintenance
IsLumenMaintenanceClaimed boolean

Set to true if lumen maintenance is claimed for this product. If claimed, the LumenMaintenancePercent, LumenMaintenanceHours, and LumenMaintenanceTemperature fields are required.

LumenMaintenancePercent number

Percentage of lumen maintenance calculated at the specified LumenMaintenanceHours and LumenMaintenanceTemperature, as calculated by the provided TM-21 Calculator documentation

LumenMaintenanceHours integer

Hour span used to calculate the LumenMaintenancePercentage

LumenMaintenanceTemperature integer

Temperature span used to calculate the LumenMaintenancePercentage

Product Submission APIs

This section provides the methods that can be used to send different HTTP requests to the products list.

GET product/:id - Retrieving an existing Product

Finds the product with the specified id

Parameters:
id integer

The id of the product you want to retrieve. All product ids are integer values greater than 0

Example Request:

Uri

GET - https://lightingfacts.com/api/product/3

Example Result:

200

A full Product Data object

400

The Id value is less than or equal to 0

401

You do not have ownership of this product

403

You do not have permission to access this product

404

The product with the specified id was not found in the products list. Note: 404 only occurs if the id is greater than 0

500

A server-side error occurred while completing your request

POST product - Creating a new Product

Creates a new product and stores it in the products list. It automatically assigns a unique id to the submitted product. The action uses a HTTP POST method. If the one or more attribute values fail the validation, then the "ProductStatus" property is set to "Incomplete", else it is set to "Complete". You cannot perform the "Product Submit" action until the "ProductStatus" property is set to "Complete"

Parameters:
body object

A full or partial Product Data object. The SSLProductID will be assigned after the product is created

Example Request:

Uri

POST - https://lightingfacts.com/api/product

Body

{
    modelNumber:    'model number xyz-123',
    brand:          'brand xyz', 
}
Example Result:

200

A full Product Data object

400

The product associated with the specified id is not complete and cannot be submitted

401

You are not authorized to submit this product

404

The product with the specified id does not exist in the products list

500

The server encountered an unexpected condition which prevented it from fulfilling the request

PUT product/:id - Update a Product

Updates the product submitted data. The action uses HTTP PUT method. If the updated product has some invalid values, the ProductStatus is set to "Incomplete", else it is set to "Complete"

Parameters:
id integer

The id of the product you want to update. All product ids are integer values greater than 0

body object

A full Product Data object with modified values

Example Request:

Uri

PUT - https://lightingfacts.com/api/product/0001

Body

    {
        modelNumber:    'model number xyz-123',
        brand:          'brand xyz', 
    }
Example Result:

200

A full Product Data object with udpated values

400

The product associated with the specified id is not complete and cannot be submitted

401

You are not authorized to modify this product

404

The product with the specified id does not exist in the products list

500

The server encountered an unexpected condition which prevented it from fulfilling the request

DELETE product/:id - Deleting a Product

Deletes the product with the specified id from the products list. Products can only be deleted when they have an status of Incomplete or Complete.

Parameters:
id integer

The id of the product to delete. All product ids are integer values greater than 0

Example Request:

Uri

DELETE - https://lightingfacts.com/api/product/0001

Example Result:

200

The product has been deleted

400

The product cannot be deleted in its current state

401

You are not authorized to modify this product

404

The product was not found in the system

500

The server encountered an unexpected condition which prevented it from fulfilling the request

POST product/:id/submit - Submit a Product

Submits the product with the specified id that has successfully passed the validations and was saved

Parameters:
id integer

The id of the product to update. All product ids are integer values greater than 0

Example Request:

Uri

POST - https://lightingfacts.com/api/product/3/submit

Body

{
modelNumber:    'model number xyz-123',
brand:          'brand xyz', 
}
Example Result:

200

The product has been submitted and will be reviewed by the LightingFacts team.

400

The product associated with the specified id is not complete and cannot be submitted

401

You are not authorized to submit this product

404

The product with the specified id does not exist in the LightingFacts system

500

The server encountered an unexpected condition which prevented it from fulfilling the request

POST product/:id/archive - Archive a Published Product

Archives a product and removes it from the LightingFacts Products list. Products can only be archived after they have been published

Parameters:
id integer

The id of the product to archive. All product ids are integer values greater than 0

Example Request:

Uri

POST - https://lightingfacts.com/api/product/3/archive

Example Result:

200

The product has been archived and is removed from the LightingFacts Products list

400

The product is already archived or is not in a valid state to be archived

401

You are not authorized to archive this product

404

A product with the specified id does not exist in the LightingFacts system

500

The server encountered an unexpected condition which prevented it from fulfilling the request

GET product/:id/family - Retrieve a Product Family

Retrieves the specified product and all associated products

Parameters:
id integer

The id of the product to retrieve all associated products of. All product ids are integer values greater than 0

Example Request:

Uri

GET - https://lightingfacts.com/api/product/3/family

Example Result:

200

A collection of Product Data objects, of the specified product and all associated products

401

You are not authorized to access this product family

404

A product with the specified id does not exist in the LightingFacts system

500

The server encountered an unexpected condition which prevented it from fulfilling the request

GET product/:id/parent - Retrieve Parent Products

Returns all parent products associated to the specified product

Parameters:
id integer

The id of the product to retrieve all parent products of. All product ids are integer values greater than 0

Example Request:

Uri

GET - https://lightingfacts.com/api/product/3/parent

Example Result:

200

A collection of Product Data objects, of the parent products of the specified product

401

You are not authorized to access this product family

404

A product with the specified id does not exist in the LightingFacts system

500

The server encountered an unexpected condition which prevented it from fulfilling the request

GET product/:id/child - Retrieve Child Products

Returns all child products associated to the specified product

Parameters:
id integer

The id of the product to retrieve all child products of. All product ids are integer values greater than 0

Example Request:

Uri

GET - https://lightingfacts.com/api/product/3/child

Example Result:

200

A collection of Product Data objects, of the child products of the specified product

401

You are not authorized to access this product family

404

A product with the specified id does not exist in the LightingFacts system

500

The server encountered an unexpected condition which prevented it from fulfilling the request

GET product/:id/validate - Validate Product Data

Validates a saved product against the LightingFacts product requirements. A product must be valid before it can be submitted

Parameters:
id integer

The id of the product to retrieve all child products of. All product ids are integer values greater than 0

Example Request:

Uri

GET - https://lightingfacts.com/api/product/3/validate

Example Result:

200

The product is valid and can be submitted

401

You are not authorized to access this product

404

A product with the specified id does not exist in the LightingFacts system

500

The server encountered an unexpected condition which prevented it from fulfilling the request

POST product/:id/fileupload/:category - Upload a File to a Submission

Uploads a new documentation file, which is associated to a product saved in the product list. The action uses HTTP POST method. Each action has an associated product ID (SSLProductID) and the category of the documentation.

Parameters:
id integer

The product id. All product ids are integer values greater than 0

category string

The type of documentation being uploaded

Example Request:

Uri

POST - https://lightingfacts.com/api/product/3/fileupload/lm80

Body

The file contents. Can be sent using jquery or other common ajax upload libraries

Example Result:

200

The file was uploaded and attached to the submission

400

An error occurred uploading the file

401

You are not authorized to access this product

404

A product with the specified id does not exist in the LightingFacts system

500

The server encountered an unexpected condition which prevented it from fulfilling the request

DELETE product/filedelete/:filecode - Remove a File from a Product Submission

Deletes a file with the specified File Code. The action uses a HTTP DELETE method. If you delete a 'required' file and try to submit a product, it will fail

Parameters:
filecode string

The file code

Example Request:

Uri

DELETE - https://lightingfacts.com/api/product/filedelete/abCdEfghIjK

Example Result:

200

The file with the specified File Code is deleted

401

You are not authorized to access this product submission

404

A file with the specified file code does not exist in the LightingFacts system

500

The server encountered an unexpected condition which prevented it from fulfilling the request