The official Python library for the Patch API.
For a complete API reference, check out Patch's API Reference..
Add the library to your requirements.txt file:
patch_api >= 1.5.0Then run:
pip install -r requirements.txtOr install it directly with
pip install patch-api- Python 3.6.1
After installing the gem, you'll have to initialize it with your API key which is available from the API key page in the Patch dashboard. The patch object will be used to to make calls to the Patch API:
importpatch_apipatch=patch_api.ApiClient(api_key=os.environ.get('SANDBOX_API_KEY'))
orders=patch.orders.retrieve_orders()importpatch_apipatch=patch_api.ApiClient(api_key=os.environ.get('SANDBOX_API_KEY'))
# Create an order - you can create an order# providing either amount (and unit) or total_price (and currency), but not both# Create order with amountamount=1_000_000# Pass in the amount in unit specifiedunit="g"patch.orders.create_order(amount=amount, unit=unit)
# Create an order with total pricetotal_price=5_00# Pass in the total price in smallest currency unit (ie cents for USD).currency="USD"patch.orders.create_order(total_price=total_price, currency=currency)
## You can also specify a project-id field (optional) to be used instead of the preferred oneproject_id='pro_test_1234'# Pass in the project's IDpatch.orders.create_order(project_id=project_id, amount=amount, unit=unit)
## Orders also accept a metadata field (optional)metadata= {"user": "john doe"}
patch.orders.create_order(metadata=metadata, amount=amount, unit=unit)
## Orders also accept a metadata field (optional)metadata= {"user": "john doe"}
patch.orders.create_order(metadata=metadata, amount=amount, unit=unit)
## Orders also accept an issued_to field (optional)issued_to= {"name": "Company A", "email": "envimpact@companya.com"}
patch.orders.create_order(issued_to=issued_to, amount=amount, unit=unit)
# Retrieve an orderorder_id='ord_test_1234'# Pass in the order's idpatch.orders.retrieve_order(id=order_id)
# Place an orderorder_id='ord_test_1234'# Pass in the order's idpatch.orders.place_order(id=order_id)
## Placing an order on behalf of another partyissued_to= {"name": "Company A", "email": "envimpact@companya.com"}
patch.orders.place_order(id=order_id, issued_to=issued_to)
# Cancel an orderorder_id='ord_test_1234'# Pass in the order's idpatch.orders.cancel_order(id=order_id)
# Retrieve a list of orderspage=1# Pass in which page of orders you'd likepatch.orders.retrieve_orders(page=page)Estimates allow API users to get a quote for the cost of compensating a certain amount of CO2. When creating an estimate, an order in the draft state will also be created, reserving the allocation of a project for 5 minutes. If you don't place your draft order within those 5 minutes, the order will automatically be cancelled.
importpatch_apipatch=patch_api.ApiClient(api_key=os.environ.get('SANDBOX_API_KEY'))
# Create an estimatemass_g=1_000_000# Pass in the mass in grams (i.e. 1 metric tonne)patch.estimates.create_mass_estimate(mass_g=mass_g)
## You can also specify a project-id field (optional) to be used instead of the preferred oneproject_id='pro_test_1234'# Pass in the project's IDpatch.estimates.create_mass_estimate(mass_g=mass_g, project_id=project_id)
# Create a bitcoin estimatetransaction_value_btc_sats=1000# [Optional] Pass in the transaction value in satoshispatch.estimates.create_bitcoin_estimate(transaction_value_btc_sats=transaction_value_btc_sats)
# Retrieve an estimateestimate_id='est_test_1234'patch.estimates.retrieve_estimate(id=estimate_id)
# Retrieve a list of estimatespage=1# Pass in which page of estimates you'd likepatch.estimates.retrieve_estimates(page=page)origin/main
Projects are the ways Patch takes CO2 out of the air. They can represent reforestation, enhanced weathering, direct air carbon capture, etc. When you place an order via Patch, it is allocated to a project.
When fetching projects, you can supply filters to the query to narrow your result. Currently supported filters are:
countrytypeminimum_available_mass
importpatch_apipatch=patch_api.ApiClient(api_key=os.environ.get('SANDBOX_API_KEY'))
# Retrieve a projectproject_id='pro_test_1234'# Pass in the project's IDpatch.projects.retrieve_project(id=project_id)
# Retrieve a list of projectspage=1# Pass in which page of projects you'd likepatch.projects.retrieve_projects(page=page)
# Retrieve a list of biomass projectspatch.projects.retrieve_projects(type="biomass")
# Retrieve a list of projects from Canadapatch.projects.retrieve_projects(country="CA")
# Retrieve a list of projects with at least 100 grams of available offsetspatch.projects.retrieve_projects(minimum_available_mass=100)
# Retrieve a project / all projects in a different language# See http://docs.patch.test:3000/#/internationalization for more information and supportpatch.projects.retrieve_projects(accept_language='fr')
project_id='pro_test_1234'patch.projects.retrieve_project(id=project_id, accept_language='fr')While we value open-source contributions to this SDK, the core of this library is generated programmatically. Complex additions made directly to the library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us!
On the other hand, contributions to the README, as well as new test cases are always very welcome!
This project uses pre-commit to automatically lint code on commit. Set-up lint commit the first time around using
pre-commit install
This project uses black for code formatting. To run the automatic formatting, run:
make lintSet up the required environment variable:
export SANDBOX_API_KEY=<SANDBOX API KEY>Run tests:
make testTo run an individual test:
python -m unittest test/xxx_test.pyTo build the library locally, run:
make buildIn another directory, create a file called patch.py and install the local package in this directory:
touch patch.py
pip install ../patch-pythonSet up the required environment variable:
export SANDBOX_API_KEY=<SANDBOX API KEY>To test the package locally, create a python file in a sibling directory and add the following:
importosimportpatch_apipatch=patch_api.ApiClient(api_key=os.environ.get('SANDBOX_API_KEY'))
orders=patch.orders.retrieve_orders(page=1)
print(orders)