Skip to main content
📌 Note: All SiliconCarbon endpoints require an active subscription. Successful responses are wrapped in a { "meta": {...}, "data": {...} } envelope; the documented response body for each endpoint is returned under the data key.

​
GET /api/data-hub/carbon/gpu-carbon-intensity

Calculate the carbon intensity of a GPU for a given location, using query parameters.

​
Authorization

🔒OAuth2: OAuth2PasswordBearer
Flow type: password
Token URL: token

​
Query Parameters

FieldTypeRequiredDescriptionConstraints
gpu_slugstring or nullNoGPU slug. Either gpu_slug or gpu_name must be provided.
gpu_namestring or nullNoGPU full name. If gpu_slug is filled in, full name will be overridden; if gpu_slug is not provided, full name is required.
hours_usednumberYesGPU used in hours, should be greater than 0.> 0
zipcodestringYesZip code of data center.
country_codestringYesCountry code of data center, represented in ISO 3166-1 alpha-2, e.g., US for United States.

​
Request Example

GET /api/data-hub/carbon/gpu-carbon-intensity?gpu_slug=nvidia-h100&hours_used=24&zipcode=94103&country_code=US

​
Responses

  • 200: Successful Response
{
    "meta": {
        "code": 0,
        "url": "/api/data-hub/carbon/gpu-carbon-intensity",
        "message": "OK",
        "timestamp": 1744201871
    },
    "data": {
        "carbonIntensity": 643.20,
        "gpu_slug": "nvidia-h100",
        "gpu_name": null,
        "gpu_tdp": 700,
        "zipcode": "94103",
        "country_code": "US",
        "carbon_emission_rate": 38.2857,
        "carbon_data_updated_time": "2025-04-01T00:00:00"
    }
}
  • 422: Validation Error
{
    "meta": {
        "code": 422,
        "url": "/api/data-hub/carbon/gpu-carbon-intensity",
        "message": "Parameter value error: hours_used:Input should be greater than 0",
        "timestamp": 1744201871,
        "args": [],
        "kwargs": {}
    },
    "data": {}
}
  • 500: Business Error (e.g., region not found, GPU not found, or missing GPU identifier)
{
    "meta": {
        "code": 34003,
        "url": "/api/data-hub/carbon/gpu-carbon-intensity",
        "message": "Unfortunately, we currently do not have data available for the region you selected.\nFor more information, please contact us at support@silicondata.com.",
        "timestamp": 1744201871,
        "args": [],
        "kwargs": {}
    },
    "data": {}
}

​
POST /api/data-hub/carbon/gpu-carbon-intensity

Calculate the carbon intensity of a GPU for a given location, using a JSON request body.

​
Authorization

🔒OAuth2: OAuth2PasswordBearer
Flow type: password
Token URL: token

​
Request Body

The request body must be in application/json format.
FieldTypeRequiredDescriptionConstraints
gpu_slugstring or nullNoGPU slug. Either gpu_slug or gpu_name must be provided.
gpu_namestring or nullNoGPU full name. If gpu_slug is filled in, full name will be overridden; if gpu_slug is not provided, full name is required.
hours_usednumberYesGPU used in hours, should be greater than 0.> 0
zipcodestringYesZip code of data center.
country_codestringYesCountry code of data center, represented in ISO 3166-1 alpha-2, e.g., US for United States.

​
Request Example

{
  "gpu_slug": "nvidia-h100",
  "gpu_name": null,
  "hours_used": 24,
  "zipcode": "94103",
  "country_code": "US"
}

​
Responses

  • 200: Successful Response
{
    "meta": {
        "code": 0,
        "url": "/api/data-hub/carbon/gpu-carbon-intensity",
        "message": "OK",
        "timestamp": 1744201871
    },
    "data": {
        "carbonIntensity": 643.20,
        "gpu_slug": "nvidia-h100",
        "gpu_name": null,
        "gpu_tdp": 700,
        "zipcode": "94103",
        "country_code": "US",
        "carbon_emission_rate": 38.2857,
        "carbon_data_updated_time": "2025-04-01T00:00:00"
    }
}
  • 422: Validation Error
{
    "meta": {
        "code": 422,
        "url": "/api/data-hub/carbon/gpu-carbon-intensity",
        "message": "Parameter value error: hours_used:Input should be greater than 0",
        "timestamp": 1744201871,
        "args": [],
        "kwargs": {}
    },
    "data": {}
}
  • 500: Business Error (e.g., region not found, GPU not found, or missing GPU identifier)
{
    "meta": {
        "code": 34003,
        "url": "/api/data-hub/carbon/gpu-carbon-intensity",
        "message": "Unfortunately, we currently do not have data available for the region you selected.\nFor more information, please contact us at support@silicondata.com.",
        "timestamp": 1744201871,
        "args": [],
        "kwargs": {}
    },
    "data": {}
}

​
GET /api/data-hub/carbon/zone-emission-rate

Query the carbon emission rate of a zone by zipcode and country code.

​
Authorization

🔒OAuth2: OAuth2PasswordBearer
Flow type: password
Token URL: token

​
Query Parameters

FieldTypeRequiredDescriptionConstraints
zipcodestringYesZip code.
country_codestringYesCountry code, represented in ISO 3166-1 alpha-2, e.g., US for United States.

​
Request Example

GET /api/data-hub/carbon/zone-emission-rate?zipcode=94103&country_code=US

​
Responses

  • 200: Successful Response
{
    "meta": {
        "code": 0,
        "url": "/api/data-hub/carbon/zone-emission-rate",
        "message": "OK",
        "timestamp": 1744201871
    },
    "data": {
        "carbon_emission_rate": {
            "zipcode": "94103",
            "country_code": "US",
            "country_name": "United States",
            "carbon_region_code": "US-CAL-CISO",
            "carbon_emission_rate": 38.2857,
            "carbon_emission_rate_type": "00",
            "emission_factor_type": "LC",
            "extra_data": null,
            "updated_time": "2025-04-01T00:00:00"
        }
    }
}
When no emission rate is found for the given zone, carbon_emission_rate is returned as null.
  • 422: Validation Error
{
    "meta": {
        "code": 422,
        "url": "/api/data-hub/carbon/zone-emission-rate",
        "message": "Parameter value error: zipcode:Field required",
        "timestamp": 1744201871,
        "args": [],
        "kwargs": {}
    },
    "data": {}
}

​
GET /api/data-hub/carbon/gpu-carbon-provider-intensity

Calculate the carbon intensity of a GPU hosted by a specific cloud provider region.

​
Authorization

🔒OAuth2: OAuth2PasswordBearer
Flow type: password
Token URL: token

​
Query Parameters

FieldTypeRequiredDescriptionConstraints
gpu_slugstring or nullNoGPU slug. Either gpu_slug or gpu_name must be provided.
gpu_namestring or nullNoGPU full name. If gpu_slug is filled in, full name will be overridden; if gpu_slug is not provided, full name is required.
hours_usednumberYesGPU used in hours, should be greater than 0.> 0
providerstringYesName of the provider.
provider_codestringYesUnique code of the provider region.

​
Request Example

GET /api/data-hub/carbon/gpu-carbon-provider-intensity?gpu_slug=nvidia-h100&hours_used=24&provider=Amazon%20Web%20Services&provider_code=us-east-1

​
Responses

  • 200: Successful Response
{
    "meta": {
        "code": 0,
        "url": "/api/data-hub/carbon/gpu-carbon-provider-intensity",
        "message": "OK",
        "timestamp": 1744201871
    },
    "data": {
        "carbonIntensity": 643.20,
        "gpu_slug": "nvidia-h100",
        "gpu_name": null,
        "gpu_tdp": 700,
        "hour": 24,
        "provider": "Amazon Web Services",
        "provider_code": "us-east-1",
        "carbon_emission_rate": 38.2857,
        "carbon_data_updated_time": "2025-04-01T00:00:00"
    }
}
  • 422: Validation Error
{
    "meta": {
        "code": 422,
        "url": "/api/data-hub/carbon/gpu-carbon-provider-intensity",
        "message": "Parameter value error: provider_code:Field required",
        "timestamp": 1744201871,
        "args": [],
        "kwargs": {}
    },
    "data": {}
}
  • 500: Business Error (e.g., provider code not found, GPU not found, or missing GPU identifier)
{
    "meta": {
        "code": -1,
        "url": "/api/data-hub/carbon/gpu-carbon-provider-intensity",
        "message": "No matching data found for provider_code us-east-1 in sd_data_center.",
        "timestamp": 1744201871,
        "args": [],
        "kwargs": {}
    },
    "data": {}
}

​
POST /api/data-hub/carbon/batch/gpu-carbon-intensity

Batch query the carbon intensity of multiple GPUs in a single request. A maximum of 50 items may be submitted per request.

​
Authorization

🔒OAuth2: OAuth2PasswordBearer
Flow type: password
Token URL: token

​
Request Body

The request body must be in application/json format.
FieldTypeRequiredDescriptionConstraints
dataArrayNoList of the GPU carbon intensity querying arguments.Max 50 items

​
data (Array)

FieldTypeRequiredDescriptionConstraints
gpu_slugstring or nullNoGPU slug. If gpu_name is None, this field should be filled in.
gpu_namestring or nullNoGPU name. If gpu_slug is filled in, this field will be overridden; if gpu_slug is None, this field is required.
hours_usednumberYesGPU used in hours, should be greater than 0.> 0
zipcodestringYesZipcode of data center.
country_codestringYesCountry code of data center, represented in ISO 3166-1 alpha-2, e.g., US for United States.

​
Request Example

{
  "data": [
    {
      "gpu_slug": "nvidia-h100",
      "gpu_name": null,
      "hours_used": 24,
      "zipcode": "94103",
      "country_code": "US"
    },
    {
      "gpu_slug": "nvidia-a100",
      "gpu_name": null,
      "hours_used": 12,
      "zipcode": "10001",
      "country_code": "US"
    }
  ]
}

​
Responses

  • 200: Successful Response
{
    "meta": {
        "code": 0,
        "url": "/api/data-hub/carbon/batch/gpu-carbon-intensity",
        "message": "OK",
        "timestamp": 1744201871
    },
    "data": {
        "data_cnt": 2,
        "data": [
            {
                "gpu_slug": "nvidia-h100",
                "gpu_name": null,
                "gpu_tdp": 700,
                "hours_used": 24,
                "zipcode": "94103",
                "country_code": "US",
                "carbon_emission_rate": 38.2857,
                "carbon_data_updated_time": "2025-04-01T00:00:00",
                "carbon_intensity": 643.20
            },
            {
                "gpu_slug": "nvidia-a100",
                "gpu_name": null,
                "gpu_tdp": 0,
                "hours_used": 12,
                "zipcode": "10001",
                "country_code": "US",
                "carbon_emission_rate": null,
                "carbon_data_updated_time": null,
                "carbon_intensity": null
            }
        ]
    }
}
When the GPU or the carbon emission data for the given zone is not found, carbon_intensity, carbon_emission_rate, and carbon_data_updated_time are returned as null for that item.
  • 422: Validation Error
{
    "meta": {
        "code": 422,
        "url": "/api/data-hub/carbon/batch/gpu-carbon-intensity",
        "message": "Parameter value error: hours_used:Input should be greater than 0",
        "timestamp": 1744201871,
        "args": [],
        "kwargs": {}
    },
    "data": {}
}
  • 500: Business Error (e.g., batch exceeds 50 items, or an item is missing both gpu_slug and gpu_name)
{
    "meta": {
        "code": -1,
        "url": "/api/data-hub/carbon/batch/gpu-carbon-intensity",
        "message": "Exceed the upper limit of the number of querying per request, should less or equal 50 per request.",
        "timestamp": 1744201871,
        "args": [],
        "kwargs": {}
    },
    "data": {}
}

​
GET /api/data-hub/carbon/country

Query country detail information. Supports fuzzy (prefix) search by country name.

​
Authorization

🔒OAuth2: OAuth2PasswordBearer
Flow type: password
Token URL: token

​
Query Parameters

FieldTypeRequiredDescriptionConstraints
country_namestringNoCountry name; supports prefix search. If omitted, all countries are returned.

​
Request Example

GET /api/data-hub/carbon/country?country_name=United

​
Responses

  • 200: Successful Response
{
    "meta": {
        "code": 0,
        "url": "/api/data-hub/carbon/country",
        "message": "OK",
        "timestamp": 1744201871
    },
    "data": {
        "data_cnt": 1,
        "data": [
            {
                "country_name": "United States",
                "area": 9833517.0,
                "population": 331002651,
                "continent": "NA",
                "iso_3166_alpha_2": "US",
                "iso_3166_alpha_3": "USA",
                "iso_3166_numeric": "840",
                "created_time": "2024-01-01T00:00:00",
                "updated_time": "2025-04-01T00:00:00",
                "sync_time": "2025-04-01T00:00:00",
                "fips": "US",
                "capital": "Washington, D.C.",
                "default_zipcode": "20001"
            }
        ]
    }
}

​
GET /api/data-hub/carbon/default-zipcode

Query the default zipcode of a country by country code.

​
Authorization

🔒OAuth2: OAuth2PasswordBearer
Flow type: password
Token URL: token

​
Query Parameters

FieldTypeRequiredDescriptionConstraints
country_codestringYesCountry code, represented in ISO 3166-1 alpha-2, e.g., US for United States.

​
Request Example

GET /api/data-hub/carbon/default-zipcode?country_code=US

​
Responses

  • 200: Successful Response
The route returns the default zipcode as a string under the data key. 
{
    "meta": {
        "code": 0,
        "url": "/api/data-hub/carbon/default-zipcode",
        "message": "OK",
        "timestamp": 1744201871
    },
    "data": "00501"
}
If the country has no zipcodes, data is returned as an empty string.
  • 422: Validation Error
{
    "meta": {
        "code": 422,
        "url": "/api/data-hub/carbon/default-zipcode",
        "message": "Parameter value error: country_code:Field required",
        "timestamp": 1744201871,
        "args": [],
        "kwargs": {}
    },
    "data": {}
}

​
GET /api/data-hub/carbon/providers/

Get the list of all data center providers.

​
Authorization

🔒OAuth2: OAuth2PasswordBearer
Flow type: password
Token URL: token

​
Query Parameters

This endpoint takes no query parameters.

​
Request Example

GET /api/data-hub/carbon/providers/

​
Responses

  • 200: Successful Response
{
    "meta": {
        "code": 0,
        "url": "/api/data-hub/carbon/providers/",
        "message": "OK",
        "timestamp": 1744201871
    },
    "data": {
        "providers": [
            "Amazon Web Services",
            "Google Cloud Platform",
            "Azure"
        ]
    }
}

​
GET /api/data-hub/carbon/providers//codes

Get the region codes for a given provider by provider name.

​
Authorization

🔒OAuth2: OAuth2PasswordBearer
Flow type: password
Token URL: token

​
Path Parameters

FieldTypeRequiredDescriptionConstraints
provider_namestringYesName of the provider.

​
Request Example

GET /api/data-hub/carbon/providers/Amazon%20Web%20Services/codes

​
Responses

  • 200: Successful Response
{
    "meta": {
        "code": 0,
        "url": "/api/data-hub/carbon/providers/Amazon Web Services/codes",
        "message": "OK",
        "timestamp": 1744201871
    },
    "data": {
        "provider": "Amazon Web Services",
        "codes": [
            "us-east-1",
            "us-west-2",
            "eu-west-1"
        ]
    }
}
If the provider is not found, both provider and codes are returned as null.

​
GET /api/data-hub/carbon/providers_selection//codes

Get the region codes for a given provider, restricted to a fixed set of supported providers.

​
Authorization

🔒OAuth2: OAuth2PasswordBearer
Flow type: password
Token URL: token

​
Path Parameters

FieldTypeRequiredDescriptionConstraints
provider_namestringYesName of the provider. Must be one of the supported provider names.Amazon Web Services, Google Cloud Platform, Azure

​
Request Example

GET /api/data-hub/carbon/providers_selection/Amazon%20Web%20Services/codes

​
Responses

  • 200: Successful Response
{
    "meta": {
        "code": 0,
        "url": "/api/data-hub/carbon/providers_selection/Amazon Web Services/codes",
        "message": "OK",
        "timestamp": 1744201871
    },
    "data": {
        "provider": "Amazon Web Services",
        "codes": [
            "us-east-1",
            "us-west-2",
            "eu-west-1"
        ]
    }
}
If the provider is not found or has no codes, data is returned as null.

​
GET /api/data-hub/carbon/providers_with_codes/

Get the list of all providers, each with its associated region codes.

​
Authorization

🔒OAuth2: OAuth2PasswordBearer
Flow type: password
Token URL: token

​
Query Parameters

This endpoint takes no query parameters.

​
Request Example

GET /api/data-hub/carbon/providers_with_codes/

​
Responses

  • 200: Successful Response
{
    "meta": {
        "code": 0,
        "url": "/api/data-hub/carbon/providers_with_codes/",
        "message": "OK",
        "timestamp": 1744201871
    },
    "data": {
        "data_cnt": 2,
        "data": [
            {
                "provider_name": "Amazon Web Services",
                "codes": [
                    "us-east-1",
                    "us-west-2"
                ]
            },
            {
                "provider_name": "Google Cloud Platform",
                "codes": [
                    "us-central1",
                    "europe-west1"
                ]
            }
        ]
    }
}