EN/API

Smartbiogas (SB) provides an API system that can be used to:

1. Integrate your own system to read data from SB master records:
   1. Feedstocks
   2. European Countries and Cities used in our records
   3. Subjects
   4. Units of measurement
   5. Analysis types and parameters
2. Automate the entry of warehouse loads and unloads, or sensor measurements
3. Upload analysis results

Access is not public, both for data security and privacy reasons, and to verify the data source.

It is necessary to request the SB team to "whitelist" the public IP address(es) from which the requests will originate. By default, any request will result in an "unauthorized IP" error.

The main route for SB API access is (currently version 1):

https://smartbiogas.it/api/v1

Example to view the list of feedstocks:

GET https://smartbiogas.it/api/v1/feedstocks_type

In addition to IP whitelisting, for certain resources linked to a specific plant (e.g., Warehouses and warehouse movements), a 128-character key is required. This provides an additional layer of security and uniquely identifies the plant you are working on.

This key must be presented in the request **HEADER** as shown in the example:

X-API-TOKEN: FpEycf3HmcML6Hv4qsjZBXroeWoKGyHyTMZKRO1cekFQkCADoScp5RYXjtrlQvoD5BJhVepaRjruzgux4yfVzq3pBOVoHxybA2Jc1Iu0oyBHMdRiJcjFigLtOtRUCRd1

Each route follows standard REST conventions, using the verbs GET, POST, and PATCH.

In general, the routing rules are:

General routing rules

VERB	Route	Notes
GET	https://smartbiogas.it/api/v1/[Resource]	returns the list of resources
GET	https://smartbiogas.it/api/v1/[Resource]/{resource_id}	Returns data for a specific resource
PATCH	https://smartbiogas.it/api/v1/[Resource]/{resource_id}	Where permitted, updates the SB resource with data passed in a JSON
POST	https://smartbiogas.it/api/v1/[Resource]	Where permitted, inserts a new resource into SB

Nested routes are available in the following format:

https://smartbiogas.it/api/v1/[Resource]/{resource_id}/[Sub-resource]

Example:

GET https://smartbiogas.it/api/v1/countries/19/cities which returns the list of municipalities in Italy (ID 19).

Some APIs can utilize different search parameters.

Example:

GET https://smartbiogas.it/api/v1/countries/19

GET https://smartbiogas.it/api/v1/countries?f_cod=IT

GET https://smartbiogas.it/api/v1/countries?f_description=ital (this performs a textual search; in this case it finds "Italy", but partial descriptions can be used to return multiple results)

All three requests return the same result: the first finds by ID, the second by code, and the third by description.

Results

For APIs requesting table records, the standard format is JSON.

Example of JSON returned by:

GET https://smartbiogas.it/api/v1/countries?f_description=it

[
	{
		"eu_countries_id": 19,
		"f_cod": "IT",
		"f_description": "Italy"
	},
	{
		"eu_countries_id": 21,
		"f_cod": "LT",
		"f_description": "Lithuania"
	}
]

APIs may also return errors. Generally, the error format is:

{
	"error_code": 13,
	"message": "Not Found"
}

For insertion/update APIs, a similar JSON will be returned:

{
	"error_code": 0,
	"movement_id": 4578693,
	"message": "Movement inserted correctly"
}

List of General Master Data APIs

Substrati/Feedstocks

Comuni/Cities

Paesi/Countries

Soggetti/Subjects (Natural persons with VAT number or Companies)

Measurement unit groups and types

Determinants (Master data of parameters common to all analyses)

Analysis types

The following APIs have restricted access for entities or companies generating data for multiple plants (e.g., Analysis Laboratories):

Plant List

The following APIs require the plant identification key (X-API-TOKEN) and will return results related to that specific plant:

Plant Data / Owning Company / Partners

Warehouse

Supply Contracts

Analysis

Control Points and Measurements