> ## Documentation Index
> Fetch the complete documentation index at: https://docs.silicondata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SiliconCarbon API

> API docs for accessing GPU carbon intensity and carbon emission data from Silicon Data.

> 📌 **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.

## <span style={{ color: 'white', fontWeight: 'bold', backgroundColor: '#28A745', border: '2px solid #28A745', borderRadius: '5px', padding: '5px', display: 'inline-block' }}>GET</span> /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

| Field          | Type           | Required | Description                                                                                                                    | Constraints |
| -------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| `gpu_slug`     | string or null | No       | GPU slug. Either `gpu_slug` or `gpu_name` must be provided.                                                                    |             |
| `gpu_name`     | string or null | No       | GPU full name. If `gpu_slug` is filled in, full name will be overridden; if `gpu_slug` is not provided, full name is required. |             |
| `hours_used`   | number         | Yes      | GPU used in hours, should be greater than 0.                                                                                   | > 0         |
| `zipcode`      | string         | Yes      | Zip code of data center.                                                                                                       |             |
| `country_code` | string         | Yes      | Country 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

```json theme={null}
{
    "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

```json theme={null}
{
    "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)

```json theme={null}
{
    "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": {}
}
```

***

## <span style={{ color: 'white', fontWeight: 'bold', backgroundColor: '#007BFF', border: '2px solid #007BFF', borderRadius: '5px', padding: '5px', display: 'inline-block' }}>POST</span> /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.

| Field          | Type           | Required | Description                                                                                                                    | Constraints |
| -------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| `gpu_slug`     | string or null | No       | GPU slug. Either `gpu_slug` or `gpu_name` must be provided.                                                                    |             |
| `gpu_name`     | string or null | No       | GPU full name. If `gpu_slug` is filled in, full name will be overridden; if `gpu_slug` is not provided, full name is required. |             |
| `hours_used`   | number         | Yes      | GPU used in hours, should be greater than 0.                                                                                   | > 0         |
| `zipcode`      | string         | Yes      | Zip code of data center.                                                                                                       |             |
| `country_code` | string         | Yes      | Country code of data center, represented in ISO 3166-1 alpha-2, e.g., `US` for United States.                                  |             |

### Request Example

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

### Responses

* **200**: Successful Response

```json theme={null}
{
    "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

```json theme={null}
{
    "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)

```json theme={null}
{
    "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": {}
}
```

***

## <span style={{ color: 'white', fontWeight: 'bold', backgroundColor: '#28A745', border: '2px solid #28A745', borderRadius: '5px', padding: '5px', display: 'inline-block' }}>GET</span> /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

| Field          | Type   | Required | Description                                                                    | Constraints |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------ | ----------- |
| `zipcode`      | string | Yes      | Zip code.                                                                      |             |
| `country_code` | string | Yes      | Country 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

```json theme={null}
{
    "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

```json theme={null}
{
    "meta": {
        "code": 422,
        "url": "/api/data-hub/carbon/zone-emission-rate",
        "message": "Parameter value error: zipcode:Field required",
        "timestamp": 1744201871,
        "args": [],
        "kwargs": {}
    },
    "data": {}
}
```

***

## <span style={{ color: 'white', fontWeight: 'bold', backgroundColor: '#28A745', border: '2px solid #28A745', borderRadius: '5px', padding: '5px', display: 'inline-block' }}>GET</span> /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

| Field           | Type           | Required | Description                                                                                                                    | Constraints |
| --------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| `gpu_slug`      | string or null | No       | GPU slug. Either `gpu_slug` or `gpu_name` must be provided.                                                                    |             |
| `gpu_name`      | string or null | No       | GPU full name. If `gpu_slug` is filled in, full name will be overridden; if `gpu_slug` is not provided, full name is required. |             |
| `hours_used`    | number         | Yes      | GPU used in hours, should be greater than 0.                                                                                   | > 0         |
| `provider`      | string         | Yes      | Name of the provider.                                                                                                          |             |
| `provider_code` | string         | Yes      | Unique 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

```json theme={null}
{
    "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

```json theme={null}
{
    "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)

```json theme={null}
{
    "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": {}
}
```

***

## <span style={{ color: 'white', fontWeight: 'bold', backgroundColor: '#007BFF', border: '2px solid #007BFF', borderRadius: '5px', padding: '5px', display: 'inline-block' }}>POST</span> /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.

| Field  | Type  | Required | Description                                          | Constraints  |
| ------ | ----- | -------- | ---------------------------------------------------- | ------------ |
| `data` | Array | No       | List of the GPU carbon intensity querying arguments. | Max 50 items |

#### data (Array)

| Field          | Type           | Required | Description                                                                                                         | Constraints |
| -------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------- | ----------- |
| `gpu_slug`     | string or null | No       | GPU slug. If `gpu_name` is None, this field should be filled in.                                                    |             |
| `gpu_name`     | string or null | No       | GPU name. If `gpu_slug` is filled in, this field will be overridden; if `gpu_slug` is None, this field is required. |             |
| `hours_used`   | number         | Yes      | GPU used in hours, should be greater than 0.                                                                        | > 0         |
| `zipcode`      | string         | Yes      | Zipcode of data center.                                                                                             |             |
| `country_code` | string         | Yes      | Country code of data center, represented in ISO 3166-1 alpha-2, e.g., `US` for United States.                       |             |

### Request Example

```json theme={null}
{
  "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

```json theme={null}
{
    "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

```json theme={null}
{
    "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`)

```json theme={null}
{
    "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": {}
}
```

***

## <span style={{ color: 'white', fontWeight: 'bold', backgroundColor: '#28A745', border: '2px solid #28A745', borderRadius: '5px', padding: '5px', display: 'inline-block' }}>GET</span> /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

| Field          | Type   | Required | Description                                                                   | Constraints |
| -------------- | ------ | -------- | ----------------------------------------------------------------------------- | ----------- |
| `country_name` | string | No       | Country 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

```json theme={null}
{
    "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"
            }
        ]
    }
}
```

***

## <span style={{ color: 'white', fontWeight: 'bold', backgroundColor: '#28A745', border: '2px solid #28A745', borderRadius: '5px', padding: '5px', display: 'inline-block' }}>GET</span> /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

| Field          | Type   | Required | Description                                                                    | Constraints |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------ | ----------- |
| `country_code` | string | Yes      | Country 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.

```json theme={null}
{
    "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

```json theme={null}
{
    "meta": {
        "code": 422,
        "url": "/api/data-hub/carbon/default-zipcode",
        "message": "Parameter value error: country_code:Field required",
        "timestamp": 1744201871,
        "args": [],
        "kwargs": {}
    },
    "data": {}
}
```

***

## <span style={{ color: 'white', fontWeight: 'bold', backgroundColor: '#28A745', border: '2px solid #28A745', borderRadius: '5px', padding: '5px', display: 'inline-block' }}>GET</span> /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

```json theme={null}
{
    "meta": {
        "code": 0,
        "url": "/api/data-hub/carbon/providers/",
        "message": "OK",
        "timestamp": 1744201871
    },
    "data": {
        "providers": [
            "Amazon Web Services",
            "Google Cloud Platform",
            "Azure"
        ]
    }
}
```

***

## <span style={{ color: 'white', fontWeight: 'bold', backgroundColor: '#28A745', border: '2px solid #28A745', borderRadius: '5px', padding: '5px', display: 'inline-block' }}>GET</span> /api/data-hub/carbon/providers/{provider_name}/codes

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

### Authorization

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

### Path Parameters

| Field           | Type   | Required | Description           | Constraints |
| --------------- | ------ | -------- | --------------------- | ----------- |
| `provider_name` | string | Yes      | Name of the provider. |             |

### Request Example

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

### Responses

* **200**: Successful Response

```json theme={null}
{
    "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`.

***

## <span style={{ color: 'white', fontWeight: 'bold', backgroundColor: '#28A745', border: '2px solid #28A745', borderRadius: '5px', padding: '5px', display: 'inline-block' }}>GET</span> /api/data-hub/carbon/providers\_selection/{provider_name}/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

| Field           | Type   | Required | Description                                                        | Constraints                                             |
| --------------- | ------ | -------- | ------------------------------------------------------------------ | ------------------------------------------------------- |
| `provider_name` | string | Yes      | Name 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

```json theme={null}
{
    "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`.

***

## <span style={{ color: 'white', fontWeight: 'bold', backgroundColor: '#28A745', border: '2px solid #28A745', borderRadius: '5px', padding: '5px', display: 'inline-block' }}>GET</span> /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

```json theme={null}
{
    "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"
                ]
            }
        ]
    }
}
```