singstat.client¶

Client for interacting with the SingStat API endpoints.

Example usage:

# search for a resource ID
from singstat import Client
client = Client()
resources = client.resource_id(keyword="population", search_option="all")

Methods¶

class singstat.client.client.Client(cache_backend: str | BaseCache = 'sqlite', is_test_api: bool = False)¶

Interact with SingStat’s API to access its catalogue of datasets.

Parameters:

metadata(resource_id: str) → MetadataDict¶

Return the metadata of a resource.

Parameters:: resource_id (str) – ID of the resource.
Warns RuntimeWarning:: “Empty data set returned” when response’s Data.records list has 0 items.
Returns:: Metadata of the requested resource.
Return type:: MetadataDict

Search for a list of resources.

Parameters:: kwargs (ResourceIdArgsDict) – Key-value arguments to be passed as parameters to the endpoint URL.
Raises:: APIError – search_option is not "all", "title" or "variable".
Warns RuntimeWarning:: “Empty data set returned” when response’s Data.total is 0.
Returns:: List of resources.
Return type:: ResourceIdDict

tabledata(resource_id: str, **kwargs: Unpack[TabledataArgsDict]) → TabledataDict¶

Retrieve data in a resource.

Parameters:

resource_id (str) – ID of the resource.
kwargs (TabledataArgsDict) – Key-value arguments to be passed as parameters to the endpoint URL.

Raises:

APIError – between tuple has at least one value that is less than 0.
APIError – between tuple’s first value is greater than its second value.
APIError – limit is not between 0 and 3000.
APIError – offset is less than 0.
APIError – sort_by does not match the regular expression r'^(key|value|seriesNo|rowNo|rowText) (asc|desc)$'.

Warns RuntimeWarning:

“Empty data set returned” when response’s Data.row list has 0 items.

Returns:

Records of data that match the search criteria.

Return type:

TabledataDict