SWS API Client
This library provides the user with a set of useful tools to easily interact with the FAO SWS (Statistical Working System) REST APIs.
Installation
The module is available on Pypi:
python -m pip install sws_api_client
The library requires Python 3.9+.
Modules
Beside the SWS APIs, the client covers the Campaign Manager — the platform that runs FAO's
questionnaire campaigns. CampaignManager is what a Task Manager wrapper needs and nothing more:
claim a generation run, register a questionnaire and put its bytes on it, claim a check or a harvest,
keep the claim alive with a heartbeat, and report how it went.
from sws_api_client import SwsApiClient, CampaignManager, ValidationSummary, in_minutes
cm = CampaignManager(SwsApiClient.auto())
cm.claim_validation(team_id=4, file_id=812, task_id="task-1", expires_at=in_minutes(15))
report = cm.create_file(team_id=4, campaign_id=7, name="report-812", type="validationReport")
cm.upload_content(team_id=4, file_id=report.id, path="report.html")
cm.complete_validation(
team_id=4, file_id=812, outcome="success", file_report_id=report.id,
summary=ValidationSummary(checks_run=12, passed=12, failed=0),
)
The endpoint is resolved through /discover (key campaigns_api) and the credentials travel on
every request exactly as they do for the other SWS APIs — there is nothing to configure per call.
Usage
To use the package the user needs to create an instance of the SwsApiClient class, provide it with the necessary parameters and execute the methods to query the specific endpoints.
Instantiate the client locally
There are three methods to instantiate the client:
1. Pass the sws_endpoint and the access_token to the constructor
from sws_api_client import SwsApiClient
sws_client = SwsApiClient(sws_endpoint="<sws_endpoint>", access_token="<access_token>")
2. Pass to sws_endpoint and the access_token as named arguments
We need to execute the script from command line passing --sws_endpoint and --access_token as arguments:
python script.py --sws_endpoint <endpoint> --access_token <test_access_token>
And instantiate the client in our script with the class method from_args:
from sws_api_client import SwsApiClient
sws_client = SwsApiClient.from_args()
3. Create a conf file where to store the arguments
We need to create a conf file (default name: "conf_sws_api_client.json") with the following structure:
{
"sws_endpoint": "https://sws.dev.fao.org",
"sws_token": "XXX",
"current_task_id": "XXX",
"current_execution_id": "XXX",
"authclient": {
"clientId": "XXX",
"clientSecret": "XXX",
"tokenEndpoint": "https://fao-dev.auth.eu-west-1.amazoncognito.com/oauth2/token",
"scope": "sws/user"
}
}
And instantiate the client in our script with the class method auto:
from sws_api_client import SwsApiClient
sws_client = SwsApiClient.auto()
Behind the scene it will automatically detect the fact that you are in debug mode and it will instanciate the client using the from_conf method
Instantiate the client in a SWS plugin
When working withing a SWS plugin instantiate the client as:
from sws_api_client import SwsApiClient
sws_client = SwsApiClient.auto()
Behind the scene it will automatically detect the fact that you are in a SWS plugin and it will instanciate the client using the from_env method
Instantiate the client using env variables
You can also instantiate the client using the following environment variables:
export SWS_ENDPOINT=https://sws.fao.org
export SWS_TOKEN=XXX
export SWS_USER_CREDENTIALS_SECRET_NAME=dev/sws/user_client
If you have no access to the SWS_USER_CREDENTIALS_SECRET_NAME you can use the following environment variables:
export SWS_AUTH_CLIENTID=XXX
export SWS_AUTH_CLIENTSECRET=XXX
export SWS_AUTH_TOKENENDPOINT=XXX
export SWS_AUTH_SCOPE=XXX
And instantiate the client in our script with the class method from_env:
from sws_api_client import SwsApiClient
sws_client = SwsApiClient.from_env()
Access different API Services
The library provides a set of classes to interact with the different services available in the SWS API. The available classes are:
Tagsto interact with the SWS Tags APIDatasetsto interact with the Datasets API provided by both the legacy SWS IS Api and the new Session APITasksto interact with the SWS TaskManager APIDatatableto interact with the SWS Datatable APIPluginsto interact with the SWS Plugins API
Perform requests
To perform requests you just need to call the available methods using the SwsApiClient object, as an example:
datasets = Datasets(sws_client)
dataset = datasets.get_dataset_info('aproduction')
logger.info(f"Dataset info: {dataset}")
or to get the list of tags:
tags = Tags(sws_client)
tags_list = tags.get_tags()
logger.info(f"Tags: {tags_list}")
more complete examples can be found in the example folder:
cp example/conf_sws_api_client.json.example example/conf_sws_api_client.json
# edit the file with your credentials
python3 -m venv example/.venv
source example/.venv/bin/activate
pip install -r example/requirements
python example/dataset_example.py
If you need to perform a test request not in debug mode, you can use the following command:
AWS_PROFILE=fao-dev DEBUG_MODE=FALSE SWS_USER_CREDENTIALS_SECRET_NAME=dev/sws/user_client SWS_TOKEN=YOUR_TOKEN SWS_ENDPOINT=https://sws.dev.fao.org python3 dataset_example.py
Development
Please follow the semantic release commit message format.
Branches
develop
The develop branhces is the main branch for development. All feature branches should be created from this branch any commit to the development branch will create an alpha version.
feature/*
The feature/* branches are the branches for new features. Any commit to a feature branch will create a beta version.
main
The main branch is the production branch. Any commit to the main branch will create a release version.
Release
Migrated to github test 6
3 maintainers
Metadata
3 maintainers
Release files for sws-api-client 2.23.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| sws_api_client-2.23.1.tar.gz | 74.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| sws_api_client-2.23.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 161.7 kB
Release files / sws_api_client-2.23.1.tar.gz
| Download URL | sws_api_client-2.23.1.tar.gz |
|---|---|
| Size | 74.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
be81096df081e12783cc28ba55c5f1fe57a78d6413f1696342165e23988e473e
|
|
BLAKE2b-256 checksum How to use checksums |
7dd1d00f31c30ade71415e21ed78c1b5e6ff5c3cfaae5e88863afa0bf5d2915d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 15, 2026.
Transparency logRelease files / sws_api_client-2.23.1-py3-none-any.whl
| Download URL | sws_api_client-2.23.1-py3-none-any.whl |
|---|---|
| Size | 87.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1b3c5d1c41ce2f5de7d38bec4c8b6b7e0527de8b3f63fe1dcd61306cd212ba1e
|
|
BLAKE2b-256 checksum How to use checksums |
d6b95b85e451ad12a96a52caa34556ccd5598908e11d80139a69724c51517b41
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 15, 2026.
Transparency log
