# Salient Predictions SDK
## Intended Use
The Salient SDK is a python convenience wrapper around Salient Predictions' customer-facing
[web API](https://api.salientpredictions.com/v2/documentation/api/). It also contains utility functions for manipulating and analyzing the data delivered from the API.
## Installing the SDK
The Salient SDK is a Python package that depends on Python v3.11 and installs from [PyPI](https://pypi.org/project/salientsdk):
```bash
python3 --version | grep -q '3.11' && echo "Py OK" || echo "Need Py 3.11"
pip install salientsdk poetry --upgrade
pip show salientsdk
```
If you "need Py 3.11", follow the instructions in [Getting Python 3.11](#getting-python-311).
The `install` will also get `poetry`, which `salientsdk` uses to manage dependencies.
## Usage
### Command Line
The Salient SDK contains a full command line interface that can access each of the primary
API functions without even opening Python.
```bash
# Get the version number:
salientsdk version
# Show help for all available commands:
salientsdk --help
```
To verify that you can access Salient's API, use your Salient credentials to log in. If you see errors or warnings relating to `VERIFY SSL` you may need to adjust your firewall settings.
#### Username/Password Authentication
**Using Environment Variables (Recommended):**
```bash
export SALIENT_USERNAME="your_username@example.com"
export SALIENT_PASSWORD="your_password"
# Now you can login without passing credentials
salientsdk login
# If successful, the command should return a Session object:
# <requests.sessions.Session object at 0x12cf45590>
```
**Using Command Line Arguments:**
```bash
salientsdk login -u your_username -p your_password
# If successful, the command should return a Session object:
# <requests.sessions.Session object at 0x12cf45590>
```
#### API Key Authentication
**Using Environment Variables (Recommended):**
```bash
export SALIENT_APIKEY="your_api_key"
# Now you can login with the API key
salientsdk login --apikey SALIENT_APIKEY
# If successful, the command should return a Session object:
# <requests.sessions.Session object at 0x12cf45590>
```
**Using Command Line Arguments:**
```bash
salientsdk login --apikey your_api_key
# If successful, the command should return a Session object:
# <requests.sessions.Session object at 0x12cf45590>
```
To verify that you can download data from Salient, use your Salient credentials to download historical data with the `data_timeseries` function. This will download a NetCDF file to your current directory and display its contents.
```bash
# Using environment variables (if already set):
salientsdk data_timeseries -fld all \
-lat 42 -lon -73 \
--start 2020-01-01 --end 2020-12-31
# Or with credentials directly:
salientsdk data_timeseries -fld all \
-lat 42 -lon -73 \
--start 2020-01-01 --end 2020-12-31 \
-u your_username -p your_password
```
To test that your specific Salient-issued credentials are functioning properly, try them with the `forecast_timeseries` function. Note that you may need to change the location (North America) and timescale (seasonal) if your license does not include them.
```bash
# Using environment variables (if already set):
salientsdk forecast_timeseries --variable precip \
-lat 42 -lon -73 \
--timescale seasonal --date 2020-01-01
# Or with credentials directly:
salientsdk forecast_timeseries --variable precip \
-lat 42 -lon -73 \
--timescale seasonal --date 2020-01-01 \
-u your_username -p your_password
```
### Example Notebooks
The package ships with examples that show `salientsdk` in action. You can list the file locations and copy them to a working directory for use. Let's work with the `hindcast_summary` notebook example:
```bash
mkdir salient_env && cd salient_env
# show all of the available examples:
salientsdk examples
# Copy the "hindcast_summary" example to the current directory:
salientsdk examples | grep "hindcast_summary" | xargs -I {} cp {} .
```
`salientsdk` uses the `poetry` dependency manager to set up a virtual environment with all the dependencies needed to run the examples:
```bash
# Clear out any poetry projects that may already exist
rm -f pyproject.toml
# Create a new poetry project
poetry init --no-interaction
# Get the latest version of the salient sdk
poetry add jupyter salientsdk@latest
# Create a virtual environment with the right dependencies
poetry run ipython kernel install --user --name="salient_env"
# Open the notebook and get it ready to run
poetry run jupyter notebook hindcast_summary.ipynb
```
Once the hindcast_summary notebook launches in your browser:
- If "salient env" is not already selected as a kernel:<br>
Kernel > Change Kernel > salient_env > Select
- Add your credentials to the "login" step in the first cell. Choose one approach:<br>
- **Username/Password:** Set environment variables `export SALIENT_USERNAME="your_username"` and `export SALIENT_PASSWORD="your_password"`, then use `sk.login("SALIENT_USERNAME","SALIENT_PASSWORD",verbose=False)`<br>
- **Username/Password (direct):** Use `sk.login("your_username", "your_password", verbose=False)`<br>
- **API Key:** Set environment variable `export SALIENT_APIKEY="your_api_key"`, then use `sk.login(apikey="SALIENT_APIKEY", verbose=False)`<br>
- **API Key (direct):** Use `sk.login(apikey="your_api_key", verbose=False)`
- The notebook assumes you are licenced for regions `north-america` and `europe`, and variables `temp` and `precip`. If you are not, change cell 2 to generate a request consistent with your licensing:<br>
`loc=sk.Location(region=["<region1>", "<region2>"]),`<br>
`variable=["<var1>", <var2>"],`
- Run > Run All Cells
- This will generate files in the `hindcast_summary_example` directory:<br>
`hindcast_summary_<hash>.csv` the source validation files from the API.<br>
`hindcast_summary_transposed.csv` a combined version of the results
### Via Python
In a python 3.11 script, this example code will login and request a historical ERA5 data timeseries.
#### Username/Password Authentication
```python
import salientsdk as sk
import xarray as xr
import netcdf4
# Using environment variables (recommended):
session = sk.login() # Uses SALIENT_USERNAME and SALIENT_PASSWORD environment variables
# Or pass credentials directly:
# session = sk.login("username", "password")
history = sk.data_timeseries(loc=sk.Location(lat=42, lon=-73), field="all", variable="temp", session=session)
print(xr.open_dataset(history))
```
#### API Key Authentication
```python
import salientsdk as sk
import xarray as xr
import netcdf4
# Using environment variables (recommended):
session = sk.login(apikey="SALIENT_APIKEY") # Uses SALIENT_APIKEY environment variable
# Or pass API key directly:
# session = sk.login(apikey="your_api_key")
history = sk.data_timeseries(loc=sk.Location(lat=42, lon=-73), field="all", variable="temp", session=session)
print(xr.open_dataset(history))
```
See all available functions in the [API Reference](api.md).
## Installation Help
### Getting Python 3.11
The Salient SDK requires Python 3.11 to use. If you have Python installed, you can check your version with:
```bash
python3 --version
```
To get version 3.11:
```bash
# Ubuntu:
sudo apt update
sudo apt install software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.11
```
```bash
# macOS:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew update
brew install python@3.11
```
## License
This SDK is licensed for use by Salient customers [details](https://salient-predictions.github.io/salientsdk/LICENSE/).
Copyright 2025 [Salient Predictions](https://www.salientpredictions.com/)
Raw data
{
"_id": null,
"home_page": "https://salientpredictions.com",
"name": "salientsdk",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "weather, climate, forecasting, sdk, salient, s2s",
"author": "Salient Predictions",
"author_email": "help@salientpredictions.com",
"download_url": "https://files.pythonhosted.org/packages/5c/df/7cdcf262a9bd2842d6372fda4ecc89a8b82ea97c6eb366f1c46f5f931243/salientsdk-0.3.42.tar.gz",
"platform": null,
"description": "# Salient Predictions SDK\n\n## Intended Use\n\nThe Salient SDK is a python convenience wrapper around Salient Predictions' customer-facing \n[web API](https://api.salientpredictions.com/v2/documentation/api/). It also contains utility functions for manipulating and analyzing the data delivered from the API.\n\n## Installing the SDK\n\nThe Salient SDK is a Python package that depends on Python v3.11 and installs from [PyPI](https://pypi.org/project/salientsdk):\n\n```bash\npython3 --version | grep -q '3.11' && echo \"Py OK\" || echo \"Need Py 3.11\"\npip install salientsdk poetry --upgrade\npip show salientsdk\n```\n\nIf you \"need Py 3.11\", follow the instructions in [Getting Python 3.11](#getting-python-311).\n\nThe `install` will also get `poetry`, which `salientsdk` uses to manage dependencies.\n\n## Usage\n\n### Command Line\n\nThe Salient SDK contains a full command line interface that can access each of the primary\nAPI functions without even opening Python.\n\n```bash\n# Get the version number:\nsalientsdk version\n# Show help for all available commands:\nsalientsdk --help\n```\n\nTo verify that you can access Salient's API, use your Salient credentials to log in. If you see errors or warnings relating to `VERIFY SSL` you may need to adjust your firewall settings.\n\n#### Username/Password Authentication\n\n**Using Environment Variables (Recommended):**\n\n```bash\nexport SALIENT_USERNAME=\"your_username@example.com\"\nexport SALIENT_PASSWORD=\"your_password\"\n\n# Now you can login without passing credentials\nsalientsdk login\n# If successful, the command should return a Session object:\n# <requests.sessions.Session object at 0x12cf45590>\n```\n\n**Using Command Line Arguments:**\n\n```bash\nsalientsdk login -u your_username -p your_password\n# If successful, the command should return a Session object:\n# <requests.sessions.Session object at 0x12cf45590>\n```\n\n#### API Key Authentication\n\n**Using Environment Variables (Recommended):**\n\n```bash\nexport SALIENT_APIKEY=\"your_api_key\"\n\n# Now you can login with the API key\nsalientsdk login --apikey SALIENT_APIKEY\n# If successful, the command should return a Session object:\n# <requests.sessions.Session object at 0x12cf45590>\n```\n\n**Using Command Line Arguments:**\n\n```bash\nsalientsdk login --apikey your_api_key\n# If successful, the command should return a Session object:\n# <requests.sessions.Session object at 0x12cf45590>\n```\n\nTo verify that you can download data from Salient, use your Salient credentials to download historical data with the `data_timeseries` function. This will download a NetCDF file to your current directory and display its contents.\n\n```bash\n# Using environment variables (if already set):\nsalientsdk data_timeseries -fld all \\\n-lat 42 -lon -73 \\\n--start 2020-01-01 --end 2020-12-31\n\n# Or with credentials directly:\nsalientsdk data_timeseries -fld all \\\n-lat 42 -lon -73 \\\n--start 2020-01-01 --end 2020-12-31 \\\n-u your_username -p your_password\n```\n\nTo test that your specific Salient-issued credentials are functioning properly, try them with the `forecast_timeseries` function. Note that you may need to change the location (North America) and timescale (seasonal) if your license does not include them.\n\n```bash\n# Using environment variables (if already set):\nsalientsdk forecast_timeseries --variable precip \\\n-lat 42 -lon -73 \\\n--timescale seasonal --date 2020-01-01\n\n# Or with credentials directly:\nsalientsdk forecast_timeseries --variable precip \\\n-lat 42 -lon -73 \\\n--timescale seasonal --date 2020-01-01 \\\n-u your_username -p your_password\n```\n\n### Example Notebooks\n\nThe package ships with examples that show `salientsdk` in action. You can list the file locations and copy them to a working directory for use. Let's work with the `hindcast_summary` notebook example:\n\n```bash\nmkdir salient_env && cd salient_env\n# show all of the available examples:\nsalientsdk examples\n# Copy the \"hindcast_summary\" example to the current directory:\nsalientsdk examples | grep \"hindcast_summary\" | xargs -I {} cp {} .\n```\n\n`salientsdk` uses the `poetry` dependency manager to set up a virtual environment with all the dependencies needed to run the examples:\n\n```bash\n# Clear out any poetry projects that may already exist\nrm -f pyproject.toml\n# Create a new poetry project\npoetry init --no-interaction\n# Get the latest version of the salient sdk\npoetry add jupyter salientsdk@latest\n# Create a virtual environment with the right dependencies\npoetry run ipython kernel install --user --name=\"salient_env\"\n# Open the notebook and get it ready to run\npoetry run jupyter notebook hindcast_summary.ipynb\n```\n\nOnce the hindcast_summary notebook launches in your browser:\n\n- If \"salient env\" is not already selected as a kernel:<br>\n Kernel > Change Kernel > salient_env > Select\n- Add your credentials to the \"login\" step in the first cell. Choose one approach:<br>\n - **Username/Password:** Set environment variables `export SALIENT_USERNAME=\"your_username\"` and `export SALIENT_PASSWORD=\"your_password\"`, then use `sk.login(\"SALIENT_USERNAME\",\"SALIENT_PASSWORD\",verbose=False)`<br>\n - **Username/Password (direct):** Use `sk.login(\"your_username\", \"your_password\", verbose=False)`<br>\n - **API Key:** Set environment variable `export SALIENT_APIKEY=\"your_api_key\"`, then use `sk.login(apikey=\"SALIENT_APIKEY\", verbose=False)`<br>\n - **API Key (direct):** Use `sk.login(apikey=\"your_api_key\", verbose=False)`\n- The notebook assumes you are licenced for regions `north-america` and `europe`, and variables `temp` and `precip`. If you are not, change cell 2 to generate a request consistent with your licensing:<br>\n `loc=sk.Location(region=[\"<region1>\", \"<region2>\"]),`<br>\n `variable=[\"<var1>\", <var2>\"],`\n- Run > Run All Cells\n- This will generate files in the `hindcast_summary_example` directory:<br>\n `hindcast_summary_<hash>.csv` the source validation files from the API.<br>\n `hindcast_summary_transposed.csv` a combined version of the results\n\n### Via Python\n\nIn a python 3.11 script, this example code will login and request a historical ERA5 data timeseries.\n\n#### Username/Password Authentication\n\n```python\nimport salientsdk as sk\nimport xarray as xr\nimport netcdf4\n\n# Using environment variables (recommended):\nsession = sk.login() # Uses SALIENT_USERNAME and SALIENT_PASSWORD environment variables\n\n# Or pass credentials directly:\n# session = sk.login(\"username\", \"password\")\n\nhistory = sk.data_timeseries(loc=sk.Location(lat=42, lon=-73), field=\"all\", variable=\"temp\", session=session)\nprint(xr.open_dataset(history))\n```\n\n#### API Key Authentication\n\n```python\nimport salientsdk as sk\nimport xarray as xr\nimport netcdf4\n\n# Using environment variables (recommended):\nsession = sk.login(apikey=\"SALIENT_APIKEY\") # Uses SALIENT_APIKEY environment variable\n\n# Or pass API key directly:\n# session = sk.login(apikey=\"your_api_key\")\n\nhistory = sk.data_timeseries(loc=sk.Location(lat=42, lon=-73), field=\"all\", variable=\"temp\", session=session)\nprint(xr.open_dataset(history))\n```\n\nSee all available functions in the [API Reference](api.md).\n\n## Installation Help\n\n### Getting Python 3.11\n\nThe Salient SDK requires Python 3.11 to use. If you have Python installed, you can check your version with:\n\n```bash\npython3 --version\n```\n\nTo get version 3.11:\n\n```bash\n# Ubuntu:\nsudo apt update\nsudo apt install software-properties-common\nsudo add-apt-repository ppa:deadsnakes/ppa\nsudo apt update\nsudo apt install python3.11\n```\n\n```bash\n# macOS:\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\nbrew update\nbrew install python@3.11\n```\n\n## License\n\nThis SDK is licensed for use by Salient customers [details](https://salient-predictions.github.io/salientsdk/LICENSE/).\n\nCopyright 2025 [Salient Predictions](https://www.salientpredictions.com/)\n",
"bugtrack_url": null,
"license": "LicenseRef-Custom",
"summary": "Salient Predictions Software Development Kit",
"version": "0.3.42",
"project_urls": {
"Documentation": "https://salient-predictions.github.io/salientsdk",
"Homepage": "https://salientpredictions.com",
"License": "https://sdk.salientpredictions.com/LICENSE/",
"Repository": "https://github.com/Salient-Predictions/salientsdk"
},
"split_keywords": [
"weather",
" climate",
" forecasting",
" sdk",
" salient",
" s2s"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f14c3e4ec946eb78a2615db22f98da65a913a1ae8015e237d9bbda91ec088055",
"md5": "1a3c2bf96115112b317f9d3de14bda2f",
"sha256": "bcfc3f0c49cc8d071307085875f8077c682904c55234bd7be4aa99e40515688e"
},
"downloads": -1,
"filename": "salientsdk-0.3.42-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1a3c2bf96115112b317f9d3de14bda2f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 223353,
"upload_time": "2025-07-31T18:35:18",
"upload_time_iso_8601": "2025-07-31T18:35:18.408542Z",
"url": "https://files.pythonhosted.org/packages/f1/4c/3e4ec946eb78a2615db22f98da65a913a1ae8015e237d9bbda91ec088055/salientsdk-0.3.42-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5cdf7cdcf262a9bd2842d6372fda4ecc89a8b82ea97c6eb366f1c46f5f931243",
"md5": "4bb5acbb4ae44df2d4b2d98a1afbf53c",
"sha256": "ec621bfb6e9b99b6fcc56cfdbc9cb745ba04d3a2e17f1908b80d0128a1cf1d4b"
},
"downloads": -1,
"filename": "salientsdk-0.3.42.tar.gz",
"has_sig": false,
"md5_digest": "4bb5acbb4ae44df2d4b2d98a1afbf53c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 193047,
"upload_time": "2025-07-31T18:35:19",
"upload_time_iso_8601": "2025-07-31T18:35:19.509181Z",
"url": "https://files.pythonhosted.org/packages/5c/df/7cdcf262a9bd2842d6372fda4ecc89a8b82ea97c6eb366f1c46f5f931243/salientsdk-0.3.42.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-31 18:35:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Salient-Predictions",
"github_project": "salientsdk",
"github_not_found": true,
"lcname": "salientsdk"
}
JSON
