Metadata-Version: 2.4
Name: boaviztapi
Version: 2.6.0
Summary: An API to access Boavizta's methodologies and footprint reference data
License-File: LICENSE
Requires-Python: >=3.11,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Dist: aiofile (>=3.9.0,<4.0.0)
Requires-Dist: aiohttp (>=3.13.5,<3.15.0)
Requires-Dist: fastapi (>=0.137.1,<0.138.0)
Requires-Dist: importlib-metadata (>=8.7.1,<9.0.0)
Requires-Dist: mangum (>=0.20.0,<0.21.0)
Requires-Dist: markdown (>=3.10,<4.0)
Requires-Dist: numpy (>=2.4.1,<3.0.0)
Requires-Dist: pandas (>=2.3.3,<3.0.0)
Requires-Dist: pydantic (>=2.12.5,<3.0.0)
Requires-Dist: pydantic-settings (>=2.0,<3.0)
Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
Requires-Dist: rapidfuzz (>=3.14.3,<4.0.0)
Requires-Dist: scipy (>=1.17.0,<2.0.0)
Requires-Dist: toml (>=0.10.2,<0.11.0)
Requires-Dist: urllib3 (>=2.6.3,<3.0.0)
Requires-Dist: uvicorn (>=0.40,<0.41)
Description-Content-Type: text/markdown

<p align="center">
    <img src="https://github.com/Boavizta/boaviztapi/blob/main/boaviztapi_color.svg" height="100" alt="BoaviztAPI">
</p>

<h3 align="center">
   An API to access <a href="https://boavizta.org/">Boavizta's</a> methodologies and data</a>
</h3>

---

See the [documentation](https://boavizta.github.io/boaviztapi/) for API usage and methodology.

[![Python tests](https://github.com/Boavizta/boaviztapi/actions/workflows/test.yml/badge.svg)](https://github.com/Boavizta/boaviztapi/actions/workflows/test.yml)

💬 [Join us on our public chat](https://chat.boavizta.org/signup_user_complete/?id=97a1cpe35by49jdc66ej7ktrjc)

## :dart: Objective

Boavizta aims to enhance the assessment of environmental impacts induced by ICTs in organisations by providing widespread access to our work in an automated and efficient manner.

Boavizta integrates various data and methodologies, which are combined and made accessible through this API.

Transparency and the popularisation of scientific knowledge are of utmost importance in this project, and key aspects include open-sourcing the code, versioning the impact factors, and thoroughly documenting the project.

The system follows a bottom-up approach in its development, organised into layers. The initial layer focuses on equipment. The second layer focuses on the impacts of digital services (e.g. cloud instances) or systems. However, assessing the overall global impact of ICT is currently beyond the project's scope.

## :gear: What it does

BoaviztAPI estimates the environmental impacts of digital equipment or services. You describe a piece of hardware (a server, a cloud instance, a laptop, a single component such as a CPU or an SSD) and the API returns its impacts for two phases of its life:

* **embedded**: manufacturing, transport and end of life, spread over the equipment's lifetime
* **use**: the electricity it consumes, multiplied by the impact factors of the electricity mix where it runs

By default the results cover global warming potential (`gwp`, in kgCO2eq), abiotic resource depletion (`adp`, in kgSbeq) and primary energy (`pe`, in MJ). Other criteria can be requested.

For example, the impacts of an AWS `m5.xlarge` over 8,760 hours (one year) of use:

```bash
curl "https://api.boavizta.org/v1/cloud/instance?provider=aws&instance_type=m5.xlarge&duration=8760"
```

## :fast_forward: Test it yourself (no installation)

* See our pedagogical front-end app (using the API): <https://datavizta.boavizta.org/serversimpact>

* See the OpenAPI specification: <https://api.boavizta.org/docs>

* [Documentation](https://boavizta.github.io/boaviztapi/)

* Access the demo API: <https://api.boavizta.org>

## Run a local instance

### :whale: Run API using docker

```bash
$ docker run -p 5000:5000 ghcr.io/boavizta/boaviztapi:latest
```

Access the API at http://localhost:5000.

### Install using pip package

```bash
$ pip3 install boaviztapi
```

Run the server locally with:

```bash
$ uvicorn boaviztapi.main:app --host=localhost --port 5000
```

## :computer: Development

### Prerequisite

- Python >=3.12
- [Poetry](https://python-poetry.org/) (see the [install instructions](https://python-poetry.org/docs/))
- `make`

### Setup poetry

Install dependencies and check the environment is set up correctly:

```bash
$ make install
$ make test
$ make lint
```

### Launch a development server

The development server uses [uvicorn](https://www.uvicorn.org/) and [FastAPI](https://fastapi.tiangolo.com/). You can launch the development server with the `uvicorn` CLI.

```bash
# Using uvicorn
$ make run

# Using Python directly (adds watcher)
$ make run-py
```

### Tests

You can run the tests with `pytest` via:

- `make test` to run all unit tests (using test data)
- `make test-e2e` to run end-to-end tests (using "real" data)

### Work on docs

API documentation is build with `mkdocs` and maintained under the `docs` directory.

See [how to work on documentation](docs/README.md)

### Create your own docker image and run it

Build Docker image:

```sh
# Using the makefile (recommended)
make docker-build-development
make docker-run-development

# Manual build
docker build . -t boavizta-test
docker run -p 5000:5000 boavizta-test
```

### Deploy to AWS as serverless application

You can self-host BoaviztAPI as an AWS Lambda function using [Serverless Framework](https://www.serverless.com/framework).

You must first configure:

- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)
- [Serverless Framework CLI](https://www.serverless.com/framework/docs/getting-started)

Once done, you can deploy the API with:

```sh
serverless deploy
```

When the deploy succeeds, it will show you the URLs for the deployed function, and you can call the API as normal, e.g.

```sh
# Replace the base URL with your own
curl -s "https://k9wllbzcc2.execute-api.eu-west-1.amazonaws.com/v1/server/?archetype=dellR740"
```

You can check your Lambda URL at any time with:

```sh
serverless info
```

### OpenAPI specification (Swagger)

Once API server is launched API swagger is available at [httsp://localhost:5000/docs](https://localhost:5000/docs).

## :handshake: Adopters

BoaviztAPI is used by several open-source projects and tools. See [ADOPTERS.md](./ADOPTERS.md) for the full list.

## :package: SDKs

Community client libraries exist for other languages (PHP…). See [SDKs.md](./SDKs.md) for the list.

## :woman: Contributing

See [contributing.md](./CONTRIBUTING.md).

You can build a source distribution (installable with pip) with `make build`.

## :one: Versioning

We use [Semantic Versioning 2.0.0](https://semver.org/)

|    Type     | Description                                                          |    Command        |
| :---        |    :----:                                                            |              ---: |
| MAJOR       | version when you make incompatible API changes                       | ```make major```  |
| MINOR       | version when you add functionality in a backwards compatible manner  | ```make minor```  |
| PATCH       | version when you make backwards compatible bug fixes                 | ```make patch```  |

## :two: Releasing

See the [Release Process wiki](https://github.com/Boavizta/boaviztapi/wiki/Release-Process).

## :scroll: Licence

GNU Affero General Public License v3.0


