Using the Fragalysis Python API
A work in progress Python package to interface with the Fragalysis web service via the REST API is available at github.com/xchem/fragalysis.
Installation
Install using pip:
pip install xchem-fragalysis
Usage
Get list of targets
To get a list of target dictionaries accessible with an optional authentication token:
from fragalysis.requests import target_list
targets = target_list(stack="production", token=token)
The token keyword can be ommitted if only accessing public targets, and stack can be either “production”, “staging” or the URL of another Fragalysis deployment.
The token can be found in the main menu in the Fragalysis UI (Menu > Get token), or visit <fragalysis url>/api/token
Download target
To get a list of target dictionaries accessible with an optional authentication token:
from fragalysis.requests import download_target
download_target(name=target_name, tas=target_access_string, token=token, stack="production", destination=".")
The token keyword can be ommitted the target is public, stack can be either “production”, “staging” or the URL of another Fragalysis deployment, tas is the “Target Access String” or DLS proposal-session string (e.g. lb32627-66), the destination can be any path and is “.” by default.
Note
The Fragalysis frontend may offer more options for target download than this API. Contributions to update the python API for feature parity are much appreciated.
The download_target method which will need updating is in https://github.com/xchem/fragalysis/blob/main/fragalysis/requests/download.py
The available POST request parameters to /api/download_structures can be seen in the JavaScript code for the frontend https://github.com/xchem/fragalysis-frontend/blob/staging/js/components/snapshot/modals/downloadStructuresDialog.js (see variables MAP_FILES, CRYSTALLOGRAPHIC_FILES, PERMALINK_OPTIONS, OTHERS)
Relevant developer contacts on github are @cvallee, @alanbchristie, @kaliif, and @boriskovar-m2ms.
Tracking experiment uploads
For the purpose of automated scraping you can use the target_uploads function to see if there have been any recent uploads:
from fragalysis.requests import target_uploads
uploads = target_uploads(statistics_only=True)
This returns a dictionary keyed by (target_name, target_access_string):
{
('A71EV2A', 'lb32627-66'): {
'target_id': 31,
'target_name': 'A71EV2A',
'target_access_string': 'lb32627-66',
'project_id': 1,
'last_upload_index': 8,
'last_upload_timestamp': datetime.datetime(2025, 10, 8, 12, 34, 0, 693173, tzinfo=datetime.timezone.utc)
},
...
}
You can then check last_upload_index against your most recent download, or use last_upload_timestamp to determine if a fresh download is needed.
Then use the download_target function as described above.
API reference
Request a list of target dictionaries from a Fragalysis deployment |
|
Request a target download from a Fragalysis deployment |