cams-ncp-client 0.0.5

Python Client for the CAMS NCP API.

CAMS NCP Client

Description

CAMS NCP Client is a Python package for interfacing with the CAMS NCP API. With the CAMS NCP Client, you can manage measurements, forecasts, models, and file uploads/downloads related to CAMS (Copernicus Atmosphere Monitoring Service) data.

Installation with pip

To install the package, you can use the following command:

pip install cams-ncp-client 

Building from Source

Clone the repository:

git clone https://git.vito.be/projects/MARVIN/repos/cams-ncp-client
cd cams-ncp-client

Creatw the Python environment:

conda env create --prefix ./.venv --file conda_env.yml
conda activate .\.venv

Install the package:

poetry install
poetry install -E "full"

Usage

The CamsNcpApiClient requires a base API URL to function. You can instantiate it as follows:

from cams_ncp_client import CamsNcpApiClient

client = CamsNcpApiClient(base_url="https://193.190.137.75/api")

Data retrieval

The CAMS NCP Client provides a consistent interface across different entity types (e.g., forecasts, observations, models, quantities, etc.) using a dual-method pattern for data retrieval:

find_xxx() Methods

These methods are API query functions that return results in paged Pydantic-typed objects (wrapped in a TableData[...] structure). They typically support:

Pagination (limit, offset) Sorting (order_by) Filtering using optional query parameters, such as:

• station_name

• quantity_name

• start_time/end_time

• model_name

• aggregation, etc.

Example find_forecasts():

from datetime import datetime
from cams_ncp_client import CamsNcpApiClient

client = CamsNcpApiClient(base_url="https://193.190.137.75/api") 
result = client.forecast.find_forecasts(
    quantity_name="NO2",
    station_name="42N016",
    model_name="CAMS",
    base_time_start=datetime(2024, 1, 1),
    limit=100,
    offset=0
)

This returns a TableData[ForecastHourly] object containing structured hourly forecast results.

Pagination gives fine control for handling large datasets.

find_xxx_df() Methods

These are wrapper methods that call the corresponding find_xxx() method repeatedly across pages, aggregate the results, and return the data as a Pandas DataFrame.

They are ideal for:

• Data analysis
• Visualization
• Exporting to CSV/Excel
• Integration with scientific workflows

Example find_observations_df():

from datetime import datetime
from cams_ncp_client import CamsNcpApiClient

client = CamsNcpApiClient(base_url="https://193.190.137.75/api") 

df = client.observation.find_observations_df(
    station_name="42N016",
    quantity_name="PM10",
    start_time=datetime(2023, 1, 1),
    end_time=datetime(2023, 6, 1)
)

Internally calls find_observations() over multiple pages and returns a flat pandas.DataFrame.

Feature	find_xxx()	find_xxx_df()
Returns	TableData[PydanticModel]	pandas.DataFrame
Paged API Access	Yes (manual limit + offset)	Yes (auto-pagination via max_pages)
Type Safety	Strongly typed via Pydantic	Standard DataFrame schema
Use Case	Low-level control, validation	Analysis, plotting, quick insights

Data Upload

The CAMS NCP Client also supports data submission to the API via various create_xxx() methods. These methods are used to upload new data entries such as forecasts, observations, models, stations, ...

Uploading Forecasts example:

To upload a list of hourly forecast records, use the ForecastClient.create_forecasts() method. The method expects a list of ForecastHourly objects that match the API schema.

from cams_ncp_client.client import CamsNcpApiClient
from cams_ncp_client.schemas.common import ForecastHourly
from datetime import datetime

client = CamsNcpApiClient(base_url="https://193.190.137.75/api")

forecast_data = [
    ForecastHourly(
        station_name="42N016",
        quantity_name="PM10",
        model_name="CAMS",
        base_time=datetime(2024, 5, 10, 0, 0),
        forecast_time=datetime(2024, 5, 11, 12, 0),
        value=15.3
    ),
    ForecastHourly(
        station_name="42N016",
        quantity_name="PM10",
        model_name="CAMS",
        base_time=datetime(2024, 5, 10, 0, 0),
        forecast_time=datetime(2024, 5, 11, 13, 0),
        value=16.7
    )
]

created_forecasts = client.forecast.create_forecasts(forecast_data)
print(f"Uploaded: {created_forecasts}.")

Full API

The full API documentation is available at https://cams-ncp-client.readthedocs.io/en/latest/.

Contributing

If you want to contribute to spio, please follow the standard contributing guidelines and push your changes to a new branch in https://git.vito.be/projects/MARVIN/repos/cams-ncp-client

Testing

TODO

CI/CD

TODO

Updating the Package Version

To update the package version:

1. Tag the code with the new version number in the format major.minor.fix.
2. Push the tagged code to the appropriate branch.

Pipeline Automation

The CI/CD pipeline is fully automated using Jenkins. Pipeline details are defined in the Jenkinsfile located in the repository root.

Contact

For questions or issues, please reach out to the project maintainers:

• Roeland Maes: [e-mail]

License

This project is licensed under the MIT License. See the LICENSE.md file for details.