Search

Find datasets across your repositories and Alphacast’s public catalog using the Python SDK’s search client.

alphacast.search.datasets() runs a full-text search against Alphacast’s catalog. By default it scopes to datasets your account has read access to (your own repositories plus anything you’ve been granted access to). Pass search_all=True to extend the search to every public dataset on Alphacast.

from alphacast import Alphacast

alphacast = Alphacast("YOUR_API_KEY")
results = alphacast.search.datasets("GDP Argentina")

for ds in results["data"]:
    print(ds["id"], ds["name"])

Method signature

search.datasets(
    query,
    offset=0,
    length=10,
    repository_id=None,
    search_all=False,
    exclude_deprecated=False,
)

query · str · required

Free-text search. Supports fuzzy matching, so close spellings still rank.

offset · int · default: "0"

Number of results to skip. Use with length for pagination.

length · int · default: "10"

Maximum number of results to return.

repository_id · int

Restrict results to a single repository.

search_all · bool · default: "False"

When True, search every public dataset on Alphacast. When False, search only datasets your account can already read.

exclude_deprecated · bool · default: "False"

When True, omit datasets flagged as deprecated.

Response shape

The method returns a dict:

{
  "data": [...],         # list of matching datasets
  "totalItems": 124,     # total matches across all pages
  "totalPages": 13,
  "currentPage": 1,
  "offset": 0,
}

Each entry in data includes the dataset’s id, name, description, source metadata, and other fields the search service returns. Use the id to feed dataset(id) for further reads.

Examples

Paginate through results

page1 = alphacast.search.datasets("inflation", offset=0, length=10)
page2 = alphacast.search.datasets("inflation", offset=10, length=10)

print(f"Showing {len(page1['data'])} of {page1['totalItems']} results")

Search the entire public catalog

results = alphacast.search.datasets("CPI", search_all=True)

Useful when you want to discover datasets you don’t already have access to. Public results can be downloaded directly with dataset(id).download_data(...).

Filter by repository

results = alphacast.search.datasets("employment", repository_id=42)

Exclude deprecated datasets

results = alphacast.search.datasets("GDP", exclude_deprecated=True)

Search results → download

A common pattern is to search, pick a result, and pull the data:

results = alphacast.search.datasets("Argentina inflation", search_all=True, length=5)

# Take the top hit
top = results["data"][0]
print("Selected:", top["id"], top["name"])

df = alphacast.datasets.dataset(top["id"]).download_data(format="pandas")

Notes on the underlying endpoint

search.datasets() calls the Alphacast workspace search endpoint at https://www.alphacast.io/api/search, not the standard REST API on api.alphacast.io. The SDK passes your API key as an apiKey query parameter on this endpoint — the search service does not currently support HTTP Basic Auth. Permissions are still respected: you only see what your key is authorized to read, plus any public content if search_all=True.

Next steps

• Pull a dataset by ID — see Downloading data.
• Programmatically discover what’s in a repository — see Datasets.