Request

Response

    Beta APIs are subject to change. Please avoid using them in production environments.

    Get the List of Supported Datasets

    This task shows you how to retrieve the list of sustainability datasets that are available for your Client ID. These datasets offer environmental product declarations (EPDs) and sustainability data from various sources. Since some sustainability datasets are subject to additional Data License agreements, you may not have access to all datasets via the API immediately. You can follow the link to explore the currently supported Data Providers and datasets.

    By the end of this task, you will know how to:

    • Call the datasets endpoint to get available data sources
    • Understand the structure of dataset information
    • Use pagination parameters to handle large result sets
    • Identify dataset IDs for use in subsequent tasks

    You use the following operation for this task:

    OperationHTTP Request
    List Datasets GET /v3/datasets

    Prerequisites

    Before starting this task, ensure you have:

    Step 1: Call the Datasets Endpoint

    Use the access token from Obtain an Access Token to call the datasets endpoint. This endpoint returns information about all sustainability datasets that are available for your Client ID.

    Replace <YOUR_ACCESS_TOKEN> with the actual access token you obtained in Obtain an Access Token.

    Code Examples:

    Here are examples of how to call the datasets endpoint:

    curl -v 'https://developer.api.autodesk.com/sustainability/v3/datasets' \
      -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
      -H 'Accept: application/json'
    
    const accessToken = "<YOUR_ACCESS_TOKEN>";
    const url = "https://developer.api.autodesk.com/sustainability/v3/datasets";
    
    fetch(url, {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Accept': 'application/json'
      }
    })
    .then(response => response.json())
    .then(data => {
      console.log('Available Datasets:', data.results);
    
      // Display each dataset
      data.results.forEach((dataset, index) => {
        console.log(`\nDataset ${index + 1}:`);
        console.log(`  ID: ${dataset.id}`);
        console.log(`  Name: ${dataset.name}`);
        console.log(`  Description: ${dataset.description || 'N/A'}`);
        console.log(`  Provider: ${dataset.provider.name}`);
        console.log(`  Supported Data Types: ${dataset.supportedDataTypes.join(', ')}`);
      });
    })
    .catch(error => console.error('Error:', error));
    
    Show More
    import requests
    
    access_token = "<YOUR_ACCESS_TOKEN>"
    url = "https://developer.api.autodesk.com/sustainability/v3/datasets"
    
    headers = {
        'Authorization': f'Bearer {access_token}',
        'Accept': 'application/json'
    }
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        data = response.json()
        print(f"Found {len(data['results'])} datasets:")
    
        for index, dataset in enumerate(data['results'], 1):
            print(f"\nDataset {index}:")
            print(f"  ID: {dataset['id']}")
            print(f"  Name: {dataset['name']}")
            print(f"  Description: {dataset.get('description', 'N/A')}")
            print(f"  Provider: {dataset['provider']['name']}")
            print(f"  Supported Data Types: {', '.join(dataset['supportedDataTypes'])}")
    else:
        print(f"Error: {response.status_code} - {response.text}")
    
    Show More
    using System;
    using System.Net.Http;
    using System.Threading.Tasks;
    using Newtonsoft.Json;
    
    public class DatasetsService
    {
        private readonly HttpClient _httpClient;
    
        public DatasetsService()
        {
            _httpClient = new HttpClient();
        }
    
        public async Task GetDatasetsAsync(string accessToken)
        {
            string url = "https://developer.api.autodesk.com/sustainability/v3/datasets";
    
            _httpClient.DefaultRequestHeaders.Clear();
            _httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken}");
            _httpClient.DefaultRequestHeaders.Add("Accept", "application/json");
    
            try
            {
                HttpResponseMessage response = await _httpClient.GetAsync(url);
                response.EnsureSuccessStatusCode();
    
                string jsonContent = await response.Content.ReadAsStringAsync();
                dynamic data = JsonConvert.DeserializeObject(jsonContent);
    
                Console.WriteLine($"Found {data.results.Count} datasets:");
    
                for (int i = 0; i < data.results.Count; i++)
                {
                    var dataset = data.results[i];
                    Console.WriteLine($"\nDataset {i + 1}:");
                    Console.WriteLine($"  ID: {dataset.id}");
                    Console.WriteLine($"  Name: {dataset.name}");
                    Console.WriteLine($"  Description: {dataset.description ?? "N/A"}");
                    Console.WriteLine($"  Provider: {dataset.provider.name}");
                    Console.WriteLine($"  Supported Data Types: {string.Join(", ", dataset.supportedDataTypes)}");
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error: {ex.Message}");
            }
        }
    }
    
    Show More

    Step 2: Understanding the Response

    A successful response will return a JSON object containing an array of dataset objects:

    {
      "results": [
        {
          "id": "4dad5217-8391-4880-bf44-91ef9404bbdc",
          "name": "ÖKOBAUDAT",
          "description": "With the ÖKOBAUDAT platform, the Federal Ministry of Housing, Urban Development and Building...",
          "provider": {
            "name": "okobaudat"
          },
          "supportedDataTypes": [
            "product-epds"
          ]
        },
        {
          "id": "c8bee2cd-d124-4713-869c-93bc67e87de1",
          "name": "EC3 - Building Transparency",
          "description": "The Embodied Carbon in Construction Calculator (EC3) tool is a free and easy to use tool...",
          "provider": {
            "name": "ec3"
          },
          "supportedDataTypes": [
            "baselines",
            "product-epds"
          ]
        }
      ],
      "pagination": {
        "offset": 0,
        "limit": 100,
        "totalResults": 2,
        "nextUrl": null
      }
    }
    
    Show More

    Key Response Fields:

    • results: Array of available datasets
    • results.id: Unique identifier for the dataset (you’ll need this for subsequent API calls)
    • results.name: Human-readable name of the dataset
    • results.description: Detailed description of the dataset’s data offerings
    • results.provider: Information about the data provider
    • results.provider.name: Name of the data provider
    • results.supportedDataTypes: Array of supported data types for this dataset
    • pagination: Object containing pagination metadata
    • pagination.offset: Number of results skipped from the beginning
    • pagination.limit: Maximum number of results returned in this response
    • pagination.totalResults: Total number of datasets available (may be null)
    • pagination.nextUrl: URL to retrieve the next page of results (null if on last page)

    Important Notes:

    • Save the results.id values: you’ll need these for subsequent API calls in Tasks 3-13
    • The dataset ID is what you’ll use in the {datasetId} parameter in other endpoints
    • Different datasets may support different data types (baselines, generic-estimates, industry-epds, product-epds)
    • Use pagination.nextUrl to navigate through large result sets
    • The pagination.totalResults field may be null if the total count is not available

    Step 3: Working with Pagination (Optional)

    If there are many datasets, you might need to use pagination parameters:

    curl -v 'https://developer.api.autodesk.com/sustainability/v3/datasets?limit=10&offset=0' \
      -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
      -H 'Accept: application/json'
    
    // Only the URL changes - rest of the code remains the same
    const url = "https://developer.api.autodesk.com/sustainability/v3/datasets?limit=10&offset=0";
    
    // accessToken, fetch() call and response handling unchanged...
    
    # Only the URL changes - rest of the code remains the same
    url = "https://developer.api.autodesk.com/sustainability/v3/datasets?limit=10&offset=0"
    
    # access_token, headers, requests.get(), and response handling unchanged...
    
    // Only the URL changes - rest of the method remains the same
    string url = "https://developer.api.autodesk.com/sustainability/v3/datasets?limit=10&offset=0";
    
    // HttpClient setup, request execution, and response handling unchanged...
    

    Pagination Parameters:

    • limit: Maximum number of results to return in a single response. This controls the page size for pagination and helps manage response times and memory usage.
    • offset: Number of results to skip from the beginning of the collection before returning results. This allows pagination through large datasets by specifying which result to start from. Default value is 0.

    Example Pagination Response:

    {
      "results": [
        {
          "id": "4dad5217-8391-4880-bf44-91ef9404bbdc",
          "name": "ÖKOBAUDAT",
          "description": "With the ÖKOBAUDAT platform, the Federal Ministry of Housing, Urban Development and Building...",
          "provider": {
            "name": "okobaudat"
          },
          "supportedDataTypes": [
            "product-epds"
          ]
        }
      ],
      "pagination": {
        "offset": 0,
        "limit": 1,
        "totalResults": 2,
        "nextUrl": "https://developer.api.autodesk.com/sustainability/v3/datasets?offset=1&limit=1"
      }
    }
    
    Show More

    Next Steps:

    In the next task, you’ll learn how to use a dataset ID to get the list of available EPD categories from a specific dataset.

    Troubleshooting:

    If you encounter any errors while making this request, please refer to the Error Handling section of this guide for detailed information about common error codes and their solutions.

    Common Issues:

    • Access Token Expired: If you get authentication errors, you may need to refresh your access token from Obtain an Access Token
    • Empty Results: If no datasets are returned, check that your access token has the necessary permissions