Tearsheet PDF — User Guide

Download dataset tearsheets as PDF files through the Carbon Arc Python SDK. Use client.data to fetch the rendered tearsheet for any dataset you can access in the Data Library.

A tearsheet is Carbon Arc's summary document for a dataset — overview, coverage, key metrics, use cases, and related metadata. The JSON version is available via get_dataset_information(); these methods return the same content as a PDF.

Setup

import os
from dotenv import load_dotenv
from carbonarc import CarbonArcClient

load_dotenv()

client = CarbonArcClient(
    host="https://api.carbonarc.co",
    token=os.getenv("CARBONARC_API_TOKEN_PROD"),
)

All tearsheet PDF methods live under client.data.

Finding a dataset ID

Tearsheet downloads are keyed by dataset ID (e.g. "CA0030", "CA0056").

# List datasets you can access
datasets = client.data.get_datasets()

# Or inspect a specific dataset's JSON metadata first
info = client.data.get_dataset_information("CA0030")

Use the dataset ID from the catalog, tearsheet metadata, or the Carbon Arc platform UI.

Option 1 — Save directly to disk — `download_tearsheet_pdf`

The simplest path: fetch the PDF and write it to a local file in one call.

path = client.data.download_tearsheet_pdf("CA0030")
print(path)
# e.g. /Users/you/project/tearsheet_CA0030.pdf

Save to a specific folder (created automatically if it does not exist):

path = client.data.download_tearsheet_pdf("CA0030", directory="downloads/tearsheets")

Behavior:

Writes tearsheet_{dataset_id}.pdf (e.g. tearsheet_CA0030.pdf)
Defaults to the current working directory when directory is omitted
Overwrites an existing file at the same path
Returns the absolute path to the written file

Option 2 — Work with raw bytes — `get_tearsheet_pdf`

Use this when you want the PDF in memory — upload to S3, attach to an email, stream to a web response, etc.

pdf_bytes = client.data.get_tearsheet_pdf("CA0030")

print(len(pdf_bytes), "bytes")
print(pdf_bytes[:4])  # b'%PDF'

Write the bytes yourself:

with open("my_tearsheet.pdf", "wb") as f:
    f.write(pdf_bytes)

download_tearsheet_pdf calls get_tearsheet_pdf internally, so both hit the same API endpoint.

Method reference

Method	Returns	Description
`get_tearsheet_pdf(dataset_id)`	`bytes`	Raw PDF content
`download_tearsheet_pdf(dataset_id, directory=None)`	`str`	Writes `tearsheet_{dataset_id}.pdf`; returns file path

Parameters

Parameter	Type	Description
`dataset_id`	`str`	Dataset identifier (e.g. `"CA0030"`)
`directory`	`str`, optional	Output folder for `download_tearsheet_pdf`. Defaults to `"."`

Errors

HTTP status	Meaning
404	Dataset ID does not exist or is not available to your account
401	Token is missing or invalid

These surface as requests.exceptions.HTTPError. Example handling:

import requests

try:
    path = client.data.download_tearsheet_pdf("INVALID_ID")
except requests.exceptions.HTTPError as e:
    print(e.response.status_code, e.response.text)

File-system issues (permissions, disk full) raise OSError from download_tearsheet_pdf.

End-to-end example

import os
from dotenv import load_dotenv
from carbonarc import CarbonArcClient

load_dotenv()

client = CarbonArcClient(
    host="https://api.carbonarc.co",
    token=os.getenv("CARBONARC_API_TOKEN_PROD"),
)

pdf_bytes = client.data.get_tearsheet_pdf("CA0056")
print(len(pdf_bytes), "bytes", pdf_bytes[:8])

path = client.data.download_tearsheet_pdf("CA0056")
print(path)

Method	Format	Use when
`get_dataset_information(dataset_id)`	JSON	You need structured tearsheet metadata in code
`get_tearsheet_pdf(dataset_id)`	PDF bytes	You need the rendered document in memory
`download_tearsheet_pdf(dataset_id)`	PDF file	You want a file on disk

For browsing and evaluating datasets before download, see the IDO Feed API and the Library API on client.data.