Unless stated otherwise, this page refers to Ukrainian companies and individual entrepreneurs and uses identifiers from Ukrainian public registries.
This section describes requests used to work with enterprise environmental and sector-specific reports: the report list within a specific domain, detailed structured data for reports that have it, and files related to each report.
Report list
GET /api/v1/enterprises/{registry_id}/reports/{domain}
This request returns enterprise reports within a single domain, for example air, water, or waste. The response includes the report list, available years for this selection, and links to files or detailed structured data where available.
The registry_id and domain parameters in the request path are required. registry_id is the enterprise identifier.
Available domain values can be retrieved from the Data domains request.
Example request
$ ESG_API_TOKEN="your_api_token"
$ curl "https://esg.saveecobot.com/api/v1/enterprises/00178353/reports/air?report_type_id=1" \
-H "Authorization: Bearer $ESG_API_TOKEN" \
-H 'Accept: application/json'
Example response
{
"results": {
"enterprise": { "type": "company", "registry_id": "00178353" },
"domain": { "slug": "air", "label": "Повітря" },
"items": [
{
"id": 276873,
"external_id": "AIR-2021-001",
"type_id": 9,
"type_name": "Звіт про викиди забруднюючих речовин",
"registry_id": "2-ТП-2021",
"authority_name": "Держстат",
"name": "Звіт № 2-ТП (повітря)",
"description_lines": [
"Річний звіт",
"Унікальний номер підприємства в реєстрі: AIR-2021-001"
],
"address": "Україна, Київська область, місто Київ",
"report_year": 2021,
"report_date": "2022-01-31",
"uploaded_at": "2022-02-01T10:00:00+00:00",
"downloaded_at": "2022-02-03T14:20:00+00:00",
"files_count": 1,
"links": {
"files": "https://esg.saveecobot.com/api/v1/enterprises/00178353/report-files/276873",
"details": "https://esg.saveecobot.com/api/v1/enterprises/00178353/report-details/276873"
},
"permissions": [
"123.45.67",
"33484710001"
],
"coordinates": null
}
],
"meta": {
"available_years": [2020, 2021]
},
"pagination": {
"current_page": 1,
"per_page": 20,
"total": 2,
"last_page": 1
}
},
"stats": { "..." }
}
Pagination parameters
page: page number.
Filters
year: reporting year.report_type_id: report type identifier. Available values can be retrieved from the Report types request.
Response fields
results.items[]
id: report identifier in ESG SaveEcoBot API.external_id: report identifier in the external source, if available.type_id: report type identifier.type_name: report type name.registry_id: report number or registration identifier, if available.authority_name: authority that published or maintains this type of reporting.name: report name.description_lines[]: short report description split into lines.address: address related to the report, if available.report_year: year the report was submitted for.report_date: report date or submission date.uploaded_at: date when the file was uploaded or published in the source.downloaded_at: date when the file was downloaded into ESG SaveEcoBot.files_count: number of files related to the report.links.files: link to the separate report files request.links.details: link to detailed structured report data, if available.permissions[]: list of permit numbers related to the report.coordinates: address coordinates, if allowed for the API key.coordinates.latitude: latitude.coordinates.longitude: longitude.
results.meta
available_years[]: list of years available in this selection.
Report details
GET /api/v1/enterprises/{registry_id}/report-details/{report_id}
This request returns data for a single report. Along with the object block containing short information about the report, the response returns a details block with structured annual data, if available for this report.
The registry_id and report_id parameters in the request path are required. registry_id is the enterprise identifier. report_id is the report identifier.
Example request
$ ESG_API_TOKEN="your_api_token"
$ curl "https://esg.saveecobot.com/api/v1/enterprises/00178353/report-details/276873" \
-H "Authorization: Bearer $ESG_API_TOKEN" \
-H 'Accept: application/json'
Example response
{
"results": {
"enterprise": { "type": "company", "registry_id": "00178353" },
"domain": { "slug": "air", "label": "Повітря" },
"object": {
"id": 276873,
"external_id": "325472110068",
"type_id": 9,
"type_name": "Звіт про викиди забруднюючих речовин і парникових газів в атмосферне повітря від стаціонарних джерел викидів – № 2-ТП (повітря) (річна) (Держстат)",
"registry_id": null,
"authority_name": "Державна служба статистики України",
"name": "Річний водний звіт",
"description_lines": [],
"address": null,
"report_year": 2024,
"report_date": "2025-02-10",
"uploaded_at": "2025-02-10T09:00:00+00:00",
"downloaded_at": "2025-02-10T09:15:00+00:00",
"files_count": 1,
"links": {
"files": "https://esg.saveecobot.com/api/v1/enterprises/00178353/report-files/276873",
"details": "https://esg.saveecobot.com/api/v1/enterprises/00178353/report-details/276873"
},
"permissions": []
},
"details": {
"kind": "annual_data",
"items": [
{
"code": "K00000",
"name": "Усього по підприємству (без урахування діоксиду вуглецю)",
"unit": "тонн",
"unit_decimals": 3,
"value": 10.001
}
]
}
},
"stats": { "..." }
}
Response fields
results.object
The object fields are the same as in results.items[] in the report list.
results.details
kind: structured data type. Currentlyannual_datais used for annual reports.items[]: list of structured indicators, rows, or metrics related to the report.items[].code: technical metric code.items[].name: metric name.items[].unit: measurement unit.items[].unit_decimals: number of decimals expected for the value.items[].value: numeric value.
Report files
GET /api/v1/enterprises/{registry_id}/report-files/{report_id}
This request returns files for a specific report. Along with the file list, the response also returns an object block with short information about the report.
The registry_id and report_id parameters in the request path are required. registry_id is the enterprise identifier. report_id is the report identifier.
Example request
$ ESG_API_TOKEN="your_api_token"
$ curl "https://esg.saveecobot.com/api/v1/enterprises/00178353/report-files/276873" \
-H "Authorization: Bearer $ESG_API_TOKEN" \
-H 'Accept: application/json'
Example response
{
"results": {
"enterprise": { "type": "company", "registry_id": "00178353" },
"object": {
"type": "report",
"id": 276873,
"registry_id": "2-ТП-2021",
"type_id": 9,
"type_name": "Звіт про викиди забруднюючих речовин",
"name": "Звіт № 2-ТП (повітря)"
},
"items": [
{
"id": 1,
"type_name": "PDF",
"name": "report.pdf",
"description": "Основний файл звіту",
"format": "application/pdf",
"size": 93811,
"uploaded_at": "2022-02-01T10:00:00+00:00",
"downloaded_at": "2022-02-03T14:20:00+00:00",
"links": {
"download": "https://esg.saveecobot.com/api/v1/enterprises/00178353/report-files/276873/download/1"
}
}
]
},
"stats": { "..." }
}
Response fields
results.object
type: object type. For this request, the value isreport.id: report identifier.registry_id: report number or registration identifier.type_id: report type identifier.type_name: report type name.name: report name.
results.items[]
id: report file identifier.type_name: document or file type name.name: file name.description: short file description.format: file format.size: file size in bytes.uploaded_at: date when the file was uploaded or published in the source.downloaded_at: date when the file was downloaded into ESG SaveEcoBot.links.download: file download link.
Report file download
GET /api/v1/enterprises/{registry_id}/report-files/{report_id}/download/{file_id}
This request returns the binary report file for download.
The registry_id, report_id, and file_id parameters in the request path are required. registry_id is the enterprise identifier. report_id is the report identifier. file_id is the report file identifier.
Example request
$ ESG_API_TOKEN="your_api_token"
$ curl -L "https://esg.saveecobot.com/api/v1/enterprises/00178353/report-files/276873/download/1" \
-H "Authorization: Bearer $ESG_API_TOKEN"
