Request

Response

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

    Filter Generic Estimates

    This task shows you how to retrieve generic estimates available for a specific dataset. Generic estimates provide reference environmental impact data that you can use for preliminary assessments when product-specific EPDs or baseline estimates are not applicable to your use case.

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

    • Call the generic estimates endpoint to get available generic estimates within a dataset
    • Understand the structure of generic estimate information
    • Work with pagination for large result sets
    • Prepare for filtering (as capabilities expand)

    You use the following operation for this task:

    OperationHTTP Request
    Filter Generic Estimates for Dataset POST /v3/datasets/{datasetId}/generic-estimates/list:filter

    Prerequisites

    Before starting this task, ensure you have:

    Warning

    Filter support varies by dataset. Before building filter expressions, call the Get Generic Estimates Filters endpoint to discover which filters are supported and which operators and values are allowed.


    Step 1: Call the Generic Estimates Endpoint

    Use the access token from Obtain an Access Token and a dataset ID from Get the List of Supported Datasets to call the generic estimates endpoint. This endpoint returns generic estimates available for the specified dataset. Filtering is provided via a request body object and may expand over time.

    Replace <YOUR_ACCESS_TOKEN> with the actual access token you obtained in Obtain an Access Token, and <DATASET_ID> with a dataset ID from Get the List of Supported Datasets.

    Code Examples:

    Here are examples of how to call the generic estimates endpoint:

    curl -v 'https://developer.api.autodesk.com/sustainability/v3/datasets/<DATASET_ID>/generic-estimates/list:filter' \
      -X 'POST' \
      -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -d '{
        "filters": {}
      }'
    
    Show More
    const accessToken = "<YOUR_ACCESS_TOKEN>";
    const datasetId = "<DATASET_ID>";
    const url = `https://developer.api.autodesk.com/sustainability/v3/datasets/${datasetId}/generic-estimates/list:filter`;
    
    const filterCriteria = {
      filters: {}
    };
    
    fetch(url, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify(filterCriteria)
    })
    .then(response => response.json())
    .then(data => {
      console.log(`Found ${data.results.length} generic estimates:`);
    
      data.results.forEach((estimate, index) => {
        console.log(`\nGeneric Estimate ${index + 1}:`);
        console.log(`  ID: ${estimate.id}`);
        console.log(`  Name: ${estimate.name}`);
        console.log(`  Category IDs: ${(estimate.categoryIds || []).join(', ') || 'N/A'}`);
        console.log(`  Declared Unit: ${estimate.declaredUnit?.qty} ${estimate.declaredUnit?.unit}`);
        console.log(`  Jurisdictions: ${(estimate.jurisdictions || []).join(', ') || 'N/A'}`);
        if (estimate.dataSource) {
          console.log(`  Data Source: ${estimate.dataSource.name || 'N/A'}`);
        }
      });
    
      if (data.pagination && data.pagination.nextUrl) {
        console.log(`\nMore results available. Next page: ${data.pagination.nextUrl}`);
      }
    })
    .catch(error => console.error('Error:', error));
    
    Show More
    import requests
    
    access_token = "<YOUR_ACCESS_TOKEN>"
    dataset_id = "<DATASET_ID>"
    url = f"https://developer.api.autodesk.com/sustainability/v3/datasets/{dataset_id}/generic-estimates/list:filter"
    
    headers = {
        'Authorization': f'Bearer {access_token}',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
    }
    
    filter_data = { "filters": {} }
    
    response = requests.post(url, headers=headers, json=filter_data)
    
    if response.status_code == 200:
        data = response.json()
        print(f"Found {len(data['results'])} generic estimates:")
    
        for index, estimate in enumerate(data['results'], 1):
            print(f"\nGeneric Estimate {index}:")
            print(f"  ID: {estimate['id']}")
            print(f"  Name: {estimate.get('name', 'N/A')}")
            print(f"  Category IDs: {', '.join(estimate.get('categoryIds', [])) or 'N/A'}")
            du = estimate.get('declaredUnit') or {}
            if 'qty' in du and 'unit' in du:
                print(f"  Declared Unit: {du['qty']} {du['unit']}")
            print(f"  Jurisdictions: {', '.join(estimate.get('jurisdictions', [])) or 'N/A'}")
            dataSource = estimate.get('dataSource')
            if dataSource:
                print(f"  Data Source: {dataSource.get('name', 'N/A')}")
    
        # Handle pagination
        if data.get('pagination') and data['pagination'].get('nextUrl'):
            print(f"\nMore results available. Next page: {data['pagination']['nextUrl']}")
    else:
        print(f"Error: {response.status_code} - {response.text}")
    
    Show More
    using System;
    using System.Net.Http;
    using System.Text;
    using System.Threading.Tasks;
    using Newtonsoft.Json;
    
    public class GenericEstimatesService
    {
        private readonly HttpClient _httpClient;
    
        public GenericEstimatesService()
        {
            _httpClient = new HttpClient();
        }
    
        public async Task GetGenericEstimatesAsync(string accessToken, string datasetId)
        {
            string url = $"https://developer.api.autodesk.com/sustainability/v3/datasets/{datasetId}/generic-estimates/list:filter";
    
            _httpClient.DefaultRequestHeaders.Clear();
            _httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken}");
            _httpClient.DefaultRequestHeaders.Add("Accept", "application/json");
    
            var filterData = new { filters = new { } };
            string jsonContent = JsonConvert.SerializeObject(filterData);
            var content = new StringContent(jsonContent, Encoding.UTF8, "application/json");
    
            try
            {
                HttpResponseMessage response = await _httpClient.PostAsync(url, content);
                response.EnsureSuccessStatusCode();
    
                string responseContent = await response.Content.ReadAsStringAsync();
                dynamic data = JsonConvert.DeserializeObject(responseContent);
    
                Console.WriteLine($"Found {data.results.Count} generic estimates:");
    
                for (int i = 0; i < data.results.Count; i++)
                {
                    var estimate = data.results[i];
                    Console.WriteLine($"\nGeneric Estimate {i + 1}:");
                    Console.WriteLine($"  ID: {estimate.id}");
                    Console.WriteLine($"  Name: {estimate.name ?? "N/A"}");
                    Console.WriteLine($"  Category IDs: {string.Join(", ", estimate.categoryIds ?? new string[]{ })}");
                    if (estimate.declaredUnit != null)
                    {
                        Console.WriteLine($"  Declared Unit: {estimate.declaredUnit.qty} {estimate.declaredUnit.unit}");
                    }
                    Console.WriteLine($"  Jurisdictions: {string.Join(", ", estimate.jurisdictions ?? new string[]{ })}");
                    if (estimate.dataSource != null)
                    {
                        Console.WriteLine($"  Data Source: {estimate.dataSource.name ?? "N/A"}");
                    }
                }
    
                if (data.pagination?.nextUrl != null)
                {
                    Console.WriteLine($"\nMore results available. Next page: {data.pagination.nextUrl}");
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error: {ex.Message}");
            }
        }
    }
    
    Show More

    Step 2: Understanding the Response

    A successful response will return a JSON object containing a list of generic estimate entries:

    {
      "results": [
        {
          "id": "ge-550e8400-e29b-41d4-a716-446655440000",
          "name": "Ready-Mix Concrete, 4000 psi",
          "categoryIds": [
            "Concrete",
            "Steel"
          ],
          "declaredUnit": {
            "qty": 1,
            "unit": "m3"
          },
          "jurisdictions": [
            "US",
            "CA"
          ],
          "dataSource": {
            "name": "Acme Materials Inc.",
            "url": "https://www.example.com"
          }
        }
      ],
      "pagination": {
        "offset": 0,
        "limit": 25,
        "totalResults": 150,
        "nextUrl": "https://developer.api.autodesk.com/sustainability/v3/datasets/f81d4fae-7dec-11d0-a765-00a0c91e6bf6/generic-estimates/list:filter?offset=25&limit=25"
      },
      "appliedFilters": {},
      "ignoredFilters": {}
    }
    
    Show More

    Key Response Fields:

    • results: Array of generic estimate items
    • results.id: Unique identifier for the generic estimate (you’ll need this for Get Generic Estimate Details)
    • results.name: Display name of the generic estimate
    • results.categoryIds: Array of category identifiers (empty array if none specified)
    • results.declaredUnit: Declared unit for measurements (object with qty and unit)
    • results.jurisdictions: Geographic regions where the estimate applies (empty array if none specified)
    • results.dataSource: Data Source information (null if generic/industry average data)
    • results.dataSource.name: Name of the data source
    • results.dataSource.url: Website URL of the data source
    • pagination: Pagination information for large result sets
    • pagination.offset: Number of results skipped from the beginning
    • pagination.limit: Maximum number of results returned in this response
    • pagination.totalResults: Total number of estimates available (may be null)
    • pagination.nextUrl: URL to retrieve the next page of results (null if on last page)
    • appliedFilters: Map of filter keys to the requested vs. applied filter values (with optional warnings when a value was dropped)
    • appliedFilters.*.requested: The filter value the client asked for (object with op and value)
    • appliedFilters.*.applied: The filter value the connector actually applied (object with op and value)
    • appliedFilters.*.warnings: Optional human-readable notes about values that could not be applied
    • ignoredFilters: Map of unrecognised filter keys to the reason they were ignored
    • ignoredFilters.*.reason: Human-readable explanation of why the filter key was not used

    Important Notes:

    • Save the results.id values: you’ll need these for Get Generic Estimate Details
    • The generic estimate ID is what you’ll use in the {genericEstimateId} parameter in other endpoints
    • Some generic estimates may have data source information, while others represent industry average data (dataSource will be null)
    • Use pagination.nextUrl to navigate through large result sets

    Step 3: Working with Generic Estimates

    Practical Uses:

    • Preliminary Assessments: Use generic estimates for early-stage environmental impact assessments
    • Reference Data: Compare generic estimates to understand typical environmental impacts for materials
    • Regional Context: Consider jurisdictions to ensure regionally relevant analysis
    • Category Filtering: Use categoryIds to understand what material categories are available

    Pagination Handling:

    When dealing with many generic estimates, use pagination. Check pagination.nextUrl to fetch additional pages until it is absent.

    Notes on Filtering:

    Filtering is provided via the request body and may expand in future releases. For now, sending an empty filters object will return the available generic estimates for the dataset.

    Next Steps:

    In the next task, you’ll learn how to retrieve detailed information about a specific generic estimate using the ID obtained from this task.

    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: