Client Module¶

Represents a CAM2 client application.

class CAM2CameraDatabaseAPIClient.client.Client(clientID, clientSecret)[source]¶

Class representing a CAM2 client application.

clientID¶: str – Id of the client application.

clientSecret¶: str – Secret of the client application.

token¶

str – Token for the client to access the CAM2 database. Each token expires in 5 minutes.

[User does not need to provide this attribute]

Note

In order to access the package, register a new application by contacting the CAM2 team at https://www.cam2project.net/.

Client initialization method.

Parameters:	clientID (str) – Id of the client application. clientSecret (str) – Secret of the client application.
Raises:	`InvalidClientIdError` – If the clientID is not in the correct format. ClientID should have a fixed length of 96 characters. `InvalidClientSecretError` – If the client secret is not in the correct format. Client secret should have a length of at least 71 characters.

base_URL = 'https://cam2-api.herokuapp.com/'¶

str – Static variable to store the base URL.

This is the URL of CAM2 Database API. User is able to send API calls directly to this URL.

register(owner, permissionLevel='user')[source]¶

Create a client to use CamraDatabaseAPI

Warning

You can only use this function if your client has webUI permission.

Parameters:

owner (str) – Username of the owner of the client application.
permissionLevel (str, optional) – Permission level of the owner of the client application. Default permission level is ‘user’.

Returns:

str – Client id of the newly registered client application.
str – Client secret of the newly registered client application.

Example

webUI_client = Client(clientID, clientSecret) # WebUI team developer created an client object webUI_client.register(ownerName, permissionLevel)

User with webUI permission will use this method to register a client with owner’s name and permission level. Scenario:

Developer in webUI team wants to register a client for normal user whose name is Bob webUI_client = Client(‘1’, ‘1’) webUI_client.register(‘Bob’, ‘user’)

update_owner(clientID, owner)[source]¶

Update owner’s username for the given clientID.

Warning

You can only use this function if your client has webUI permission.

Parameters:	clientID (str) – Client Id of the application. owner (str, optional) – (Optional) Username of owner.
Returns:	Success message.
Return type:	str

Example

webUI_client = Client(clientID, clientSecret) webUI_client.update_owner(userClientID, ownerName)

User with webUI permission will use this method to update owner of a client given specific clientID. Scenario:

Developer in webUI team wants to change the owner of clientID 2123 from ‘Bob’ to ‘Ken’ webUI_client.update_owner(‘2123’, ‘Ken’)

update_permission(clientID, permissionLevel)[source]¶

Update owner’s permissionLevel for the given clientID.

Warning

You can only use this function if your client has webUI permission.

Parameters:	clientID (str) – Client Id of the application. permissionLevel (str, optional) – Permission level of client.
Returns:	Success message.
Return type:	str

Example

webUI_client = Client(clientID, clientSecret) webUI_client.update_permission(userClientID, ‘webUI’)

User with webUI permission will use this method to update permission of a client given specific clientID. Scenario:

Developer in webUI team wants to change the permission of clientID 2123 from ‘user’ to ‘webUI’ webUI_client.update_permission(‘2123’, ‘webUI’)

reset_secret(clientID)[source]¶

A method to reset client secret.

Warning

You can only use this function if your client has webUI permission.

Parameters:	clientID (str) – Client Id of the application.
Returns:	New clientSecret
Return type:	str

Example

webUI_client = Client(clientID, clientSecret) webUI_client.reset_secret(userClientID)

User with webUI permission will use this method to reset secret key of a client given specific clientID. Scenario:

Developer in webUI team wants to change the secret key of clientID 2123 webUI_client.reset_secret(‘2123’‘)

client_ids_by_owner(owner)[source]¶

A method to get all client ids for a specific owner.

Warning

You can only use this function if your client has webUI permission.

Parameters:	owner (str) – Username of the owner of the client application.
Returns:	A list of client’s ID owned by the user.
Return type:	list of str

Example

webUI_client = Client(clientID, clientSecret) webUI_client.client_ids_by_owner(ownerName)

User with webUI permission will use this method to get a list of clientIDs that belongs to a user. Scenario:

Developer in webUI team wants to get all clientIDs that belongs to user named ‘Bob’ webUI_client.client_ids_by_owner(‘Bob’)

usage_by_client(clientID, owner)[source]¶

A method to get number of API requests made by a given clientID.

Warning

You can only use this function if your client has webUI permission.

Parameters:	clientID (str) – Client’s ID of the application. owner (str) – Username of the owner of the client application.
Returns:	The number of requests made by the client.
Return type:	int

Example

webUI_client = Client(clientID, clientSecret) webUI_client.usage_by_client(userClientID, ownerName)

User with webUI permission will use this method to get number of API requests made by clientID 2123 Scenario:

Developer in webUI team wants to get number of API requests made by clientID 2123 whose owner is ‘Bob’ webUI_client.usage_by_client(‘2123’, ‘Bob’)

write_camera(**kwargs)[source]¶

Add or update camera in the database.

Warning

You can only use this function if your client has admin permission.

Examples

Adding a camera of type ‘IP’ into the database:

Each type of camera has its unique fields. Please check the Parameters of this function or Camera for eligible fields of the type of camera you are working on.

Create a keyword arguments dictionary which contains all the parameters needed to create the camera (fields with value None can be omitted):

>>> kwargs = {'camera_type': 'ip', 'is_active_image': True,
              'is_active_video': False, 'ip': '127.0.0.1', 'snapshot_url': None,
              'm3u8_url': None, 'cameraID': None, ...}

Pass the keyword arguments dictionary to the write_camera function:

>>> client.write_camera(**kwargs)

Or, you can directly call the method with all parameters:

>>> client.write_camera(camera_type='ip', is_active_image=True,
              is_active_video=False, ip='127.0.0.1', snapshot_url=None, ...)

Updating a camera of type ‘IP’ in the database:

One subtle difference of updating an existing camera from adding a new camera is that only cameraID, camera_type, and fields to be updated need to be included as a parameter with non-None value to update the camera.

Create a keyword arguments dictionary which contains all the parameters needed to update the camera; in this example, user will update the ip address of this ip camera:

>>> kwargs = {'ip': '127.0.0.2', 'camera_type': 'ip',
              'cameraID': '5ae0ecbd336359291be74c12'}

Pass the keyword arguments dictionary to the write_camera function:

>>> client.write_camera(**kwargs)

Or, you can directly call the method with all parameters:

>>> client.write_camera(camera_type='ip', ip='127.0.0.2',
              cameraID='5ae0ecbd336359291be74c12')

Adding or updating a camera of type ‘non_ip’:

Following the above example of adding and updating IP camera, the only difference lies in the required fields.

Example of adding a non-ip camera into database:

>>> kwargs = {'camera_type': 'non_ip', 'is_active_image': True,
              'is_active_video': False, 'ip': None, 'snapshot_url': test_url,
              'm3u8_url': None, 'cameraID': None, ...}
>>> client.write_camera(**kwargs)

Example of updating the snapshot url and country of a camera of type ‘non_ip’:

>>> client.write_camera(camera_type='non_ip', snapshot_url='updated_test_url',
              country='JP', cameraID': '5ae0ecbd336359291be74c12'}

Adding or updating a camera of type ‘stream’:

Following the above example of adding and updating IP camera, the only difference lies in the required fields.

Example of adding a stream camera into database:

>>> client.write_camera(camera_type='stream', is_active_image=True,
              is_active_video=False, m3u8_url='test_url', cameraID=None, ...)

Example of updating the m3u8_url of a camera of type ‘stream’:

>>> write_camera(camera_type='stream', m3u8_url='test_url',
              cameraID='5ae0ecbd336359291be74c12')

Parameters:

camera_type (str) – Type of camera. Allowed values: ‘ip’, ‘non_ip’, ‘stream’. | This parameter is required for adding camera.
is_active_image (bool) – Whether the camera is active and can get images. This field can identify true/false case-insensitively and 0/1. | This parameter is required for adding camera.
is_active_video (bool) – Whether the camera is active and can get video. This field can identify true/false case-insensitively and 0/1. | This parameter is required for adding camera.
ip (str) – (IP camera only) IP address of the camera. | This parameter is required for adding an IP camera.
snapshot_url (str) – (non-IP camera only) Url to retrieve snapshots from the camera. | This parameter is required for adding a non-IP camera.
m3u8_url (str) – (Stream camera only) Url to retrieve stream from the camera. | This parameter is required for adding a stream camera.
cameraID (str) – CameraID of the camera to be updated. | This parameter is required for updating camera.

Warning

Including a cameraID in your write_camera request will update and overwrite the corresponding camera information in the database. Please ensure that the updated information is correct.

Other Parameters:
	legacy_cameraID (int, optional) – Original ID of the camera in SQL database. frame_rate (int, optional) – Frame-rate of the camera. source (str, optional) – Source of camera. latitude (int or float, optional) – Latitude of the camera location. longitude (int or float, optional) – Longitude of the camera location. country (str, optional) – Country which the camera locates at. state (str, optional) – State which the camera locates at. city (str, optional) – City which the camera locates at. resolution_width (int, optional) – Resolution width of the camera. resolution_height (int, optional) – Resolution height of the camera. utc_offset (int, optional) – Time difference between UTC and the camera location. timezone_id (str, optional) – Time zone ID of the camera location. timezone_name (str, optional) – Time zone name of the camera location. reference_logo (str, optional) – Reference logo of the camera. reference_url (str, optional) – Reference url of the camera. port (str or int, optional) – (ip_camera only) Port to connect to camera. brand (str, optional) – (ip_camera only) Brand of the camera. model (str, optional) – (ip_camera only) Model of the camera. image_path (str, optional) – (ip_camera only) Path to retrieve images from the camera. video_path (str, optional) – (ip_camera only) Path to retrieve video from the camera.
Raises:	`AuthenticationError` – If the client secret of this client object does not match the clientID. `FormatError` – Informartion of invalid parameter or unexpected paramters. `ResourceConflictError` – The legacy_cameraID already exist in the database. `InternalError` – If there is an API internal error. `ResourceNotFoundError` – If no camera exists with the cameraID specified in the parameter. Or If the client id of this client object does not match any client in the database.
Returns:	The camera ID for the successfully added or updated camera.
Return type:	str

Note

When adding or updating a camera you must supply the corresponding required parameters and may also include any number of the optional parameters defined below in ‘Other Parameters’.

When Adding a new camera: Do not include any cameraID when adding new cameras to the database. When the camera is added to the database, a new cameraID will be assigned and returned to the user.

When updating an existing camera in the database you must include the corresponding cameraID and any fields you wish to update. If in any occasion you need to change an existing camera to a different type, you must include the corresponding retrieval method data. (i.e. To change an IP camera to non-ip camera, you must include values of snapshot_url and camera_type) Updating field in retrieval method requires you to also specify the type of camera. (i.e. To change the image_path of an IP camera, you should specify the camera_type and image_path)

camera_by_id(cameraID)[source]¶

A method to get a camera object by using camera’s ID

Parameters:	cameraID (str) – Id of the camera in the database.
Returns:	A camera object.
Return type:	`Camera`

Example

client.camera_by_id(‘5ae0ecbc336359291be74c0b’)

Example

user_client = Client(clientID, clientSecret) user_client.camera_by_id(cameraID)

Programmer with ‘user’ permission will use this method to get a camera object with specified cameraID Scenario:

Normal user wants to get a camera object which has a id of ‘12938263’ user_client.camera_by_id(‘12938263’)

camera_by_legacy_id(legacy_cameraID)[source]¶

A method to get a camera object by using camera’s legacy ID

Parameters:	legacy_cameraID (str) – legacy_cameraID of the camera in the database.
Returns:	A camera object.
Return type:	`Camera`

camera_by_list_id(cameraID_list=None, legacy_cameraID_list=None)[source]¶

A method to get a list of camera object by using a list of camera’s legacy ID or ID.

Parameters:	legacy_cameraID_list (List) – legacy_cameraIDs of the cameras in the database. cameraID_list (List) – cameraIDs of the cameras in the database.
Returns:	List of cameras that satisfy the search criteria.
Return type:	`list` of `Camera`

search_camera(**kwargs)[source]¶

A method to search camera by attributes and location. Searching by location requires user to provide coordiantes for a desired center point and a radius in meters. The search will carry out in the area bounded by the circle. Each time, this function can return a maximum of 100 cameras. Getting more cameras can be achieved by calling this function multiple times with offest parameter.

Examples

Searching a camera of type ‘IP’ into the database with city as ‘West Lafayette’

Create a keyword arguments dictionary which contains all the parameters needed to search the camera:

kwargs = {‘camera_type’: ‘ip’, ‘city’: ‘West Lafayette’}

Pass the keyword arguments dictionary to the search_camera function:: a_client = Client(‘id’, ‘pass’) a_client.search_camera(**kwargs)

Another way to search for cameras with the same parameters can be done by

the following code:: a_client = Client(‘id’, ‘pass’) a_client.search_camera(camera_type=’ip’, city=’West Lafayette’)

Parameters:	latitude (float, optional) – Latitude of the center of the circle area to be searched. Latitude ranges between +90 and -90. Please specify longitude and radius if this parameter value is provided. longitude (float, optional) – Longitude of the center of the circle area to be searched. Longitude ranges between +180 and -180. Please specify latitude and radius if this parameter value is provided. radius (float, optional) – Radius in km of the circle area to be searched. Radius should be positive Please specify latitude and longitude if this parameter value is provided. offset (int, optional) – Number of cameras skipped. Since each time this function can return max 100 cameras, calling this function the second time adding offset=100 will get the second 100 cameras beyond the first list of 100 cameras. camera_type (str, optional) – Type of camera. Allowed values: ‘ip’, ‘non_ip’, ‘stream’. source (str, optional) – Source of the camera. country (str, optional) – Country which the camera locates at. state (str, optional) – State which the camera locates at. city (str, optional) – City which the camera locates at. resolution_width (int, optional) – Resolution width of the camera. It has to be positive. resolution_height (int, optional) – Resolution height of the camera. It has to be positive. is_active_image (bool, optional) – If the camera is active and can get images. This field can identify true/false case-insensitively and 0/1. is_active_video (bool, optional) – If the camera is active and can get video. This field can identify true/false case-insensitively and 0/1.
Returns:	List of cameras that satisfy the search criteria.
Return type:	`list` of `Camera`
Raises:	`FormatError` – If type of argument value is not expected for the given field. Or there are unexpected keywords in kwargs. Or radius cannot is less than 0. Or incorrect latitude range. (it should be between +90 and -90) Or incorrect longitude range. (it should be between +180 and -180) `AuthenticationError` – If the client secret of this client object does not match the clientID. `ResourceNotFoundError` – If the client id of this client object does not match any client in the database. `InternalError` – If there is an API internal error.

check_cam_exist(camera_type, **kwargs)[source]¶

A method to get one or more camera object that has the given retrieval method in the database.

Parameters:	camera_type (str) – Type of the camera. Type can only be ‘ip’, ‘non_ip’, or ‘stream’. ip (str, optional) – [for IP camera] Ip address of the camera. Although marked as optional, this field is required when the camera type is ‘ip’. port (Int, optional) – [for IP camera] Port of the camera. If no port provided, it will be set to default 80. image_path (str, optional) – [for IP camera] Path to retrieve images from the camera. video_path (str, optinal) – [for IP camera] Path to retrievae vidoe from the camera. snapshot_url (str, optional) – [for non_IP camera] Url to retrieval image frames from the camera. Although marked as optional, this field is required when the camera type is ‘non_ip’. m3u8_url (str, optional) – [for stream camera] Url to retrieval video stream from the camera. Although marked as optional, this field is required when the camera type is ‘stream’.
Returns:	List of camera objects that has the given retrieval method. If there are no cameras matches the provided retrieval information, an empty list will be returned.
Return type:	`list` of `Camera`
Raises:	`FormatError` – If camera type is not valid. Or camera type is not provided. Or ip is not provided when the camera type is ‘ip’. Or snapshot_url is not provided when the camera type is ‘non_ip’. Or m3u8_url is not provided when the camera ytpe is ‘stream’. Or there are unexpected keywords in kwargs. `AuthenticationError` – If the client secret of this client object does not match the clientID. `ResourceNotFoundError` – If the client id of this client object does not match any client in the database. `InternalError` – If there is an API internal error.

get_change_log(start=None, end=None, offset=None)[source]¶

A method to get change_log for a specific time period

Parameters:	start (str, optional) – Start time of the log user desires to query end (str, optional) – End time of the log user desires to query offset (str, optional) – How many logs to skip
Returns:	A list of objects containing cameraID and creation time of the log.
Return type:	`list` of dict
Raises:	`AuthenticationError` – If the client secret of this client object does not match the clientID. `InternalError` – If there is an API internal error. `FormatError` – If type of argument value is not expected for the given field.

Example

webUI_client = Client(clientID, clientSecret) webUI_client.get_change_log(start, end, offset)

Programmer with ‘webUI’ permission will use this method to get change_log for a specific time period Scenario:

Developer in webUI team wants to get 10 activities between the below time frame webUI_client.get_change_log(‘2018-08-27T15:53:00’, ‘2018-08-27T16:53:00’, 10)