Queries

When querying the CAM2 database through our API, you can use three different methods:

  • retrieve all cameras from the database
  • retrieve all cameras in the certain radius from a given geographical location
  • retrieve certain number of cameras closest to a given geographical location In addition to these three different types of queries, you can apply certain filters to your query results, as described here. Note: all examples below are performed using curl, but any other software with similar capabilities can be used.

Retrieve all cameras

In order to get all cameras from the CAM2 database, you send a GET request to the API at the URI <cam2_domain>/cameras.json. The response to this request is a JSON representation of the cameras. For example:

curl --request "GET" <cam2api_domain>/cameras.json

Query by radius

In case you want to retrieve all cameras that are in certain radius from a given geographical location, you need to send the query specifying latitude and longitude of that location, as well as radius in which you want these cameras to be. The response to this request is a list of cameras in a JSON representation. Note: For latitude we use negative number south of equator and positive north of equator, for longitude negative values west of Prime Meridian and positive values east of Prime Meridian. Unit for the radius is kilometers. Example:

curl --request "GET" <cam2api_domain>/query/lat=20.12,lon=13.621,radius=12.json

In this example, the result would be a JSON representation of all cameras that are in the 12 kilometers radius from the point 20.12 degrees North, 13.621 East. Note: latitude and longitude can have up to 4 decimal places, while radius has to be an integer.

Query by number

If you want to get certain number of cameras that are closest to a given geographical location, you need to send the query specifying latitude and longitude of that location, as well as the number of cameras that you want to receive. The response to this request is a list of cameras in a JSON representation. Note: For latitude we use negative number south of equator and positive north of equator, for longitude negative values west of Prime Meridian and positive values east of Prime Meridian. Example:

curl --request "GET" <cam2api_domain>/query/lat=-11,lon=0.4562,count=54.json

In this example, the result would be a JSON representation of 54 cameras that are closest to the point 11 degrees South, 0.4562 East. Note: latitude and longitude can have up to 4 decimal places, while count has to be an integer.

Filters

In addition to the queries described above, you can specify your request even further by adding some query parameters (filters). These filters are applied to all cameras in the database, after which your particular query is processed. You can specify as many query parameters as you want, and they will be connected by logical AND. The list of available filters:

  • city - city where cameras are located
  • state - state where cameras are located (only applicable to the US)
  • country - country where cameras are located
  • camera_type - type of the cameras (Non_IP or IP)
  • lat - latitude of the cameras
  • lat_min - minimum latitude of all cameras (everything north of the latitude)
  • lat_max - maximum latitude of all cameras (everything south of the latitude)
  • lng - longitude of the cameras
  • lng_min - minimum longitude of all cameras (everything east of the longitude)
  • lng_max - maximum longitude of all cameras (everything west of the longitude)
  • framerate - framerate of the cameras
  • framerate_min - minimum framerate of the cameras
  • framerate_max - maximum framerate of the cameras
  • source - provider of the cameras
  • resolution_w - resolution width of the cameras
  • resolution_w_min - minimum resolution width of the cameras
  • resolution_w_max - maximum resolution width of the cameras
  • resolution_h - resolution height of the cameras
  • resolution_h_min - minimum resolution height of the cameras
  • resolution_h_max - maximum resolution height of the cameras
  • id - camera id
  • video - is camera a video stream (True or False)
  • outdoors - is camera outdoors (True or False)
  • traffic - is camera recording traffic (True or False)
  • inactive - is camera inactive (True or False)
  • added_before - specifying the latest date that the cameras were added at (MM/DD/YYYY)
  • added_after - specifying the earliest date that the cameras were added at (MM/DD/YYYY)
  • updated_before - specifying the latest date that the cameras were updated at (MM/DD/YYYY)
  • updated_after - specifying the earliest date that the cameras were updated at (MM/DD/YYYY)

Examples:

Instead of just getting all cameras from the database, we may want to get all cameras from India that have framerate between 0.3 and 20 frames per second. In that case, we would send the following request:

curl --request "GET" <cam2api_domain>/cameras.json?country=Kenya&framerate_min=0.3&framerate_max=20

If we want to get 54 cameras closest to the latitude -11 degrees and longitude 0.4562 degrees that have been added to the database after July 4th of 2017, we would send the following request:

curl --request "GET" <cam2api_domain>/query/lat=-11,lon=0.4562,count=54.json?added_after=07/04/2017