datagovsg: interact with Data.gov.sg’s API

Release v1.0.3.

Python 3 PyPi PyPi status GNU General Public License v3.0 Documentation Status

This is an unofficial Python package for interacting with APIs available at Data.gov.sg.

Installing the package

Install the package using pip:

pip install datagovsg

Using the package

The main steps are:

  1. Import a class.

  2. Instantiate an object from the class.

  3. Call a function on that object.

Contents

Package Overview

Interacting with Data.gov.sg’s API is done through one of four clients, where each client corresponds with a “set” of endpoints. (Data.gov.sg doesn’t categorise its endpoints by set, but it can be assumed from the endpoints’ path directories.)

The four clients are: Ckan, Environment, Technology and Transport.

Each client contains several public functions, one function per endpoint. A function’s name is the same as its corresponding endpoint’s ending path.

Most functions accept named arguments, where an argument corresponds with a parameter that the endpoint accepts.

Why have separate clients instead of one single client?

Without knowing how Data.gov.sg’s API will evolve, and noticing that the endpoints were themselves already partitioned into “sets”, it seemed like a good idea to keep each set of endpoints in its own contextual client. This allows for each “set” of endpoints to be customised on their own, e.g. the Environment endpoints allow for either a date or date-time to be specified, whereas the Transport endpoints don’t.

Package Reference

datagovsg

Module contents
datagovsg.Ckan

alias of datagovsg.ckan.client.Client

datagovsg.Environment

alias of datagovsg.environment.client.Client

datagovsg.Technology

alias of datagovsg.technology.client.Client

datagovsg.Transport

alias of datagovsg.transport.client.Client

datagovsg.exceptions

Exceptions that could occur when interacting with any API.

exception datagovsg.exceptions.APIError(message, errors=None)

Bases: Exception

Error when the API returns an error.

message

The general error message to display when the error is raised.

Type

str

errors

(optional) Other messages that were part of the raised error.

Type

list of str

datagovsg.ckan

Client for interacting with the CKAN APIs.

Example usage:

# list all available packages
from datagovsg import Ckan
ckan = Ckan()
packages = ckan.package_list()
Methods
class datagovsg.ckan.client.Client

Bases: datagovsg.client.__Client

Interact with CKAN software to access its catalogue of datasets.

Search data in a resource.

Parameters

  • resource_id (str) – ID or alias of the resource to be searched against.

  • limit (int) – (optional) Maximum number of rows to return. Default: 100.

  • offset (int) – (optional) Offset this number of rows. Default: 0.

  • fields (str) – (optional) Fields to return.

  • filters (dict) – (optional) Dictionary of matching conditions, e.g {“key1”: “a”, “key2”: “b”}.

  • q (str or dict) – (optional) Full text query. If it’s a string, it’ll search on all fields on each row. If it’s a dictionary as {“key1”: “a”, “key2”: “b”}, it’ll search on each specific field.

  • sort (str) – (optional) Comma-separated field names with ordering, e.g. “fieldname1, fieldname2 desc”.

  • records_format (str) – (optional) The format for the records return value. “objects”: list of {fieldname1: value1, …} dicts “lists”: list of [value1, value2, …] lists “csv”: comma-separated values with no header “tsv”: tab-separated values with no header Default: “objects”.

Returns

(dict) Resources that match the search criteria. All of the records are concatenated together, so there is no need for further pagination.

References

https://data.gov.sg/dataset/ckan-datastore-search

package_list(limit=None, offset=None)

Return a list of datasets on data.gov.sg.

Parameters

  • limit (int) – (optional) Maximum number of packages to return per page. Default: None, i.e. return all packages.

  • offset (int) – (optional) Offset this number of packages.

Returns

(dict) Metadata and list of packages.

References

https://data.gov.sg/dataset/ckan-package-list

package_show(package_id)

Return the metadata of a dataset (package) and its resources.

Parameters

package_id (str) – ID or name of the dataset.

Returns

(dict) Metadata and resources of the requested package.

References

https://data.gov.sg/dataset/ckan-package-show

resource_show(resource_id)

Return the metadata of a resource.

Parameters

resource_id (str) – ID of the resource.

Returns

(dict) Metadata of the requested resource.

References

https://data.gov.sg/dataset/ckan-resource-show

datagovsg.environment

Client for interacting with the Environment APIs.

Example usage:

# get the 24-hour weather forecast
from datagovsg import Environment
environment = Environment()
forecast = environment.twenty_four_hour_weather_forecast()
Methods
class datagovsg.environment.client.Client

Bases: datagovsg.client.__Client

Interact with the environment-related endpoints.

air_temperature(date_time=None, dt=None)

Get air temperature readings across Singapore.

Parameters

  • date_time (datetime) – (optional) Specific date-time to retrieve the readings. Will be standardised to SGT timezone. If both dt and date_time are specified, then date_time is used.

  • dt (date) – (optional) Specific date to retrieve the readings. If both dt and date_time are specified, then dt is NOT used.

Returns

(dict) Readings of air temperature by station.

References

https://data.gov.sg/dataset/realtime-weather-readings?resource_id=17494bed-23e9-4b3b-ae89-232f87987163

four_day_weather_forecast(date_time=None, dt=None)

Retrieve the latest 4 day weather forecast.

Parameters

  • date_time (datetime) – (optional) Specific date-time to retrieve the readings. Will be standardised to SGT timezone. If both dt and date_time are specified, then date_time is used.

  • dt (date) – (optional) Specific date to retrieve the readings. If both dt and date_time are specified, then dt is NOT used.

Returns

(dict) Weather forecast for the next 4 days by area.

References

https://data.gov.sg/dataset/weather-forecast?resource_id=4df6d890-f23e-47f0-add1-fd6d580447d1

pm25(date_time=None, dt=None)

Retrieve the latest PM2.5 information in Singapore.

Parameters

  • date_time (datetime) – (optional) Specific date-time to retrieve the readings. Will be standardised to SGT timezone. If both dt and date_time are specified, then date_time is used.

  • dt (date) – (optional) Specific date to retrieve the readings. If both dt and date_time are specified, then dt is NOT used.

Returns

(dict) Readings of PM2.5 by region.

References

https://data.gov.sg/dataset/pm2-5

psi(date_time=None, dt=None)

Retrieve the latest PSI information in Singapore.

Parameters

  • date_time (datetime) – (optional) Specific date-time to retrieve the readings. Will be standardised to SGT timezone. If both dt and date_time are specified, then date_time is used.

  • dt (date) – (optional) Specific date to retrieve the readings. If both dt and date_time are specified, then dt is NOT used.

Returns

(dict) Readings of PSI by region.

References

https://data.gov.sg/dataset/psi

rainfall(date_time=None, dt=None)

Get rainfall readings across Singapore.

Parameters

  • date_time (datetime) – (optional) Specific date-time to retrieve the readings. Will be standardised to SGT timezone. If both dt and date_time are specified, then date_time is used.

  • dt (date) – (optional) Specific date to retrieve the readings. If both dt and date_time are specified, then dt is NOT used.

Returns

(dict) Readings of rainfall by station.

References

https://data.gov.sg/dataset/realtime-weather-readings?resource_id=8bd37e06-cdd7-4ca4-9ad8-5754eb70a33d

relative_humidity(date_time=None, dt=None)

Get relative humidity readings across Singapore.

Parameters

  • date_time (datetime) – (optional) Specific date-time to retrieve the readings. Will be standardised to SGT timezone. If both dt and date_time are specified, then date_time is used.

  • dt (date) – (optional) Specific date to retrieve the readings. If both dt and date_time are specified, then dt is NOT used.

Returns

(dict) Readings of relative humidity by station.

References

https://data.gov.sg/dataset/realtime-weather-readings?resource_id=59eb2883-2ceb-4d16-85f0-7e3a3176ef46

twenty_four_hour_weather_forecast(date_time=None, dt=None)

Retrieve the latest 24 hour weather forecast across Singapore.

Parameters

  • date_time (datetime) – (optional) Specific date-time to retrieve the readings. Will be standardised to SGT timezone. If both dt and date_time are specified, then date_time is used.

  • dt (date) – (optional) Specific date to retrieve the readings. If both dt and date_time are specified, then dt is NOT used.

Returns

(dict) Weather forecast for the next 24 hours by area.

References

https://data.gov.sg/dataset/weather-forecast?resource_id=9a8bd97e-0e38-46b7-bc39-9a2cb4a53a62

two_hour_weather_forecast(date_time=None, dt=None)

Retrieve the latest two hour weather forecast across Singapore.

Parameters

  • date_time (datetime) – (optional) Specific date-time to retrieve the readings. Will be standardised to SGT timezone. If both dt and date_time are specified, then date_time is used.

  • dt (date) – (optional) Specific date to retrieve the readings. If both dt and date_time are specified, then dt is NOT used.

Returns

(dict) Weather forecast for the next 2 hours by area.

References

https://data.gov.sg/dataset/weather-forecast?resource_id=571ef5fb-ed31-48b2-85c9-61677de42ca9

uv_index(date_time=None)

Retrieve the latest UV index information in Singapore.

Parameters

date_time (datetime) – (optional) Specific date-time to retrieve the readings. Will be standardised to SGT timezone.

Returns

(dict) Readings of UV Index by station.

References

https://data.gov.sg/dataset/ultraviolet-index-uvi

wind_direction(date_time=None, dt=None)

Get wind direction readings across Singapore.

Parameters

  • date_time (datetime) – (optional) Specific date-time to retrieve the readings. Will be standardised to SGT timezone. If both dt and date_time are specified, then date_time is used.

  • dt (date) – (optional) Specific date to retrieve the readings. If both dt and date_time are specified, then dt is NOT used.

Returns

(dict) Readings of wind direction by station.

References

https://data.gov.sg/dataset/realtime-weather-readings?resource_id=5dcf8aa5-cf6a-44e4-b359-1173eecfdf4c

wind_speed(date_time=None, dt=None)

Get wind speed readings across Singapore.

Parameters

  • date_time (datetime) – (optional) Specific date-time to retrieve the readings. Will be standardised to SGT timezone. If both dt and date_time are specified, then date_time is used.

  • dt (date) – (optional) Specific date to retrieve the readings. If both dt and date_time are specified, then dt is NOT used.

Returns

(dict) Readings of wind speed by station.

References

https://data.gov.sg/dataset/realtime-weather-readings?resource_id=16035f22-37b4-4a5c-b024-ca2381f11b48

datagovsg.technology

Client for interacting with the Technology APIs.

Example usage:

# get the patents lodged today
from datagovsg import Technology
technology = Technology()
patents = technology.patents()
Methods
class datagovsg.technology.client.Client

Bases: datagovsg.client.__Client

Interact with the technology-related endpoints.

designs(date=None)

Get design applications lodged with IPOS in Singapore.

Parameters

date (date) – (optional) Specific date to retrieve the lodged designs on that date. Can be in any timezone (will be standardised to SGT.)

Returns

(dict) Design applications that have been lodged.

References

https://data.gov.sg/dataset/ipos-apis?resource_id=adf6222f-955b-4a76-892f-802a396844a1

patents(date=None)

Get patent applications lodged with IPOS in Singapore.

Parameters

date (date) – (optional) Specific date to retrieve the lodged patents on that date. Can be in any timezone (will be standardised to SGT.)

Returns

(dict) Patent applications that have been lodged.

References

https://data.gov.sg/dataset/ipos-apis?resource_id=6a030bf2-22da-4621-8ab0-9a5956a30ef3

trademarks(date=None)

Get trademark applications lodged with IPOS in Singapore.

Parameters

date (date) – (optional) Specific date to retrieve the lodged trademarks on that date. Can be in any timezone (will be standardised to SGT.)

Returns

(dict) Trademark applications that have been lodged.

References

https://data.gov.sg/dataset/ipos-apis?resource_id=1522db0e-808b-48ea-9869-fe5adc566585

datagovsg.transport

Client for interacting with the Transport APIs.

Example usage:

# get the list of available car park spaces
from datagovsg import Transport
transport = Transport()
carpark_availability = transport.carpark_availability()
Methods
class datagovsg.transport.client.Client

Bases: datagovsg.client.__Client

Interact with the transport-related endpoints.

carpark_availability(date_time=None)

Get the latest carpark availability in Singapore.

Parameters

date_time (datetime) – (optional) Specific date-time to retrieve the availabilities at that time. Can be in any timezone (will be standardised to SGT.)

Returns

(dict) Available carpark spaces.

References

https://data.gov.sg/dataset/carpark-availability

taxi_availability(date_time=None)

Get locations of available taxis in Singapore.

Parameters

date_time (datetime) – (optional) Specific date-time to retrieve the availabilities at that time. Can be in any timezone (will be standardised to SGT.)

Returns

(dict) GeoJSON of the taxi availabilities.

References

https://data.gov.sg/dataset/taxi-availability

traffic_images(date_time=None)

Get the latest images from traffic cameras all around Singapore.

Parameters

date_time (datetime) – (optional) Specific date-time to retrieve the images at that time. Can be in any timezone (will be standardised to SGT.)

Returns

(dict) Images from traffic cameras.

References

https://data.gov.sg/dataset/traffic-images

External References

Data.gov.sg’s Developer Guide

Indices and tables

License

This project is licensed under the GNU General Public License v3.0.