i-saw incident manager - 3dt group api.pdf · i-saw is a registered product of 3dt group of...

1 | P a g e i-Saw is a registered product of 3DT Group of Companies

www.3dtgroup.com

i-Saw Incident Manager API Document

version 1.4


www.3dtgroup.com

Table of Contents Rules .............................................................................................................................................................. 4

PUSH Notifications to i-Saw end-users ......................................................................................................... 4

How to register ............................................................................................................................................. 4

Companies who do not have a development team ...................................................................................... 5

Incident Detail Screen ............................................................................................................................... 5

Filter Options ........................................................................................................................................ 5

Group By ............................................................................................................................................... 5

Sorting ................................................................................................................................................... 5

Advanced Search ................................................................................................................................... 6

Export/Reporting .................................................................................................................................. 6

Grid Icons .............................................................................................................................................. 6

Incident Map ............................................................................................................................................. 6

Map Filters ............................................................................................................................................ 6

Adding an Incident .................................................................................................................................... 6

Incident Types ....................................................................................................................................... 7

i-Saw Heroes ............................................................................................................................................. 8

Misconduct ............................................................................................................................................... 8

Add Incident (Option1: use predefined Incident Input Screen) ................................................................... 9

To run this API: .......................................................................................................................................... 9

Example ..................................................................................................................................................... 9

Add Incident API (option2) ............................................................................................................................ 9

Incident Codes ........................................................................................................................................ 11

Error Codes ............................................................................................................................................. 12

Example ................................................................................................................................................... 12

Edit an Incident (option1: use predefined Incident Input Screen) ............................................................. 13

To run this API: ........................................................................................................................................ 13

Edit an Incident (option2) ........................................................................................................................... 13

Error Codes ............................................................................................................................................. 14

Example ................................................................................................................................................... 14

Request Incident Data ................................................................................................................................. 14


www.3dtgroup.com

Example ................................................................................................................................................... 15


www.3dtgroup.com

Use of any of the Incident API’s requires that the developer or integrator (known as a Data Provider)

register with 3DT Group of companies, and receive their unique Key Code.

All Incidents logged into the platform if from a Developer or Integrator, the incident is flagged and

disclosed to the public as coming from that Developer or Integrator.

All Incidents logged into the platform from the general public, the incident is flagged as “Public”.

All Incidents logged into the platform by a Data Provider, the incident is flagged as “that Data Providers

Company Name”.

Rules All incidents are monitored for:

advertising,

marketing,

email

web addresses

bad language

If found the incident is either denied or hidden from public view until corrected.

PUSH Notifications to i-Saw end-users Any person who has downloaded the i-Saw application to their phone is known as an end-user. End-

users are sent PUSH notifications under the following conditions:

When a National Alert has been submitted to the i-Saw Platform (example: Weather and Natural

Disaster Advisory, Terror Alert Advisory).

Advising the end-user that they can set themselves up to receive automated notifications based

upon their own criteria.

When a new revision is available.

When the online i-Saw Platform has been updated.

When an i-Saw Hero has been added (the end-user can opt out).

Tip’s and How-To’s (the end-user can opt out).

Data Provider Advertising (the end-user can opt out). Note: This option only applies to Data

Providers who have registered as a i-Saw Data Provider Advertiser. For more information please

email [email protected] with the subject line “i-Saw advertising”.

How to register Email [email protected] , subject line “Incident Integration Request” giving the following

information:

mailto:[email protected]



www.3dtgroup.com

a. Company Name

b. Company Registration Number

c. Company Physical Address

d. Company Phone Number

e. Contact Name

f. Contact Title

g. Contact Phone

h. Contact Email

i. Description of how your company intends using the API(‘s)

Companies who do not have a development team 3DT accommodates companies who want to integrate with “i-Saw” but do not have a development

team available to them. A request must be made by that company to [email protected]. Once

approved, a specific url link will be created for that company and they will have access to the Create

Incident Option1 and Manage Incident Option 1.

The delivered interface for companies who choose not use the “i-Saw” API can be seen below. This

interface requires only your unique “Key Code”.

Example:

https://secure.911sa.co.za/reports/V8/i-SawDataProviderControl?keyCode=ABC12345

Incident Detail Screen

Filter Options

To the right of the screen the user can request to View data specific to incidents Incident Type, City,

Province and/or Zip Code. When the user clicks on any of these options, a list of all existing incidents are

displayed. The user can at that point select which exact incidents they would like to see in the grid.

Group By

The data is grouped by the user selected Data Groups

Sorting

The data is sorted by the user selected data fields. If Group By has also been applied, they data is sorted

within each Group.


https://secure.911sa.co.za/reports/V8/i-SawDataProviderControl?keyCode=ABC12345


www.3dtgroup.com

Advanced Search

The user can Search for specific incident information.

Export/Reporting

The data as per the applied filters (if any) can be exported into XLS, XML or CSV (comma delimited)

formats.

Grid Icons

The detail grid has x3 icons to the left of each Incident

See the Incident in a separate Google Map

See all images/photos associated with that incident

Edit that Incident (This feature is ONLY available to Incident Data Providers, and only the description and photo/images can be edited)

Report Abuse on an Incident (Incident is immediately removed from view, and inspected by 3DT Administration prior to being either deleted from the system or put back in View).

Incident Map This will show by default all incident types for the country that the user’s registered country.

Each incident type is supported by specific images. The users can click on any image which will display all

details as per the detail screen.

Map Filters

The map allows data to be filtered by Incident Type and by Date Range. The default Date Range is the current day. The default Incident Type are all incidents To select multiple Incident Types, the user should select each Incident Type using ctrl+left mouse click

Adding an Incident

When an Incident is added, the “Provided by” field in the Incident database is updated with the Data Provider Company Name.

All fields are scrutinized automatically for bad language and for advertising or marketing information


www.3dtgroup.com

The Vehicle License Plate # field is made available only with certain Incident types where a vehicle may be involved.

Adding an incident always defaults to that Country.

If an Incident with the exact same incident type, date and time (within 1hr ) and location (within 250 meters) is already in the system, the Incident Reporter will be asked if they still want to add the new incident.

Incident “Types” are first grouped together by incident category and then sorted alphabetically within the respective category. There are x4 category types:

o Crime o Traffic o Weather o Natural Disasters

Incident Types

Below lists the current Incident Types and the Categories each Incident Type falls under.

Category Description

Traffic Accident Can include License Plate #

Traffic Driving Reckless Can include License Plate #

Traffic Road Closed

Traffic Power Outage

Traffic Congested Traffic

Traffic Power-line Down

Traffic Falling Rocks

Traffic Fallen Tree Blocking Road

Traffic Road Construction

Traffic Potholes or Bad Road

Traffic Traffic Light Not Working

Traffic Slippery Road

Traffic Vehicle Fire Can include License Plate #

Traffic Water Pipe Broken

Traffic Road Flooded

Crime Terror Alert

Crime Burglary

Crime Murder

Crime Carjacking Can include License Plate #

Crime Abduction Can include License Plate #

Crime Missing Person

Crime Shooting

Crime Riot

Crime Suspicious Vehicle or Person Can include License Plate #

Crime Radiation In Area

Crime Building Fire


www.3dtgroup.com

Weather Severe Weather

Weather Tornado

Weather Hail Storm

Weather Hurricane

Weather Heavy Snow

Weather Hurricane

Weather High Winds

Natural Disaster Earthquake

Natural Disaster Floods

Natural Disaster Fire

Natural Disaster Mud Slide

Natural Disaster Avalanche

Natural Disaster Tsunami

General Other

i-Saw Heroes While the i-Saw platform is primarily geared towards Incidents, 3DT like to feel that people who should

be recognized for doing a good deed in an Incident, should be recognized. These people are known as i-

Saw Heroes. Here the public can give them up to 5-Stars in recognition for their good deed. As an i-Saw

Hero is added to the i-Saw Platform, all users worldwide are informed by an i-Saw PUSH Notification.

Misconduct Users and Data Providers alike, can report in Misconduct on any Incident. Misconduct could be anything

including inappropriate language or photo’s, advertising, misuse or abuse of the i-Saw platform, etc.

When reported in that incident is automatically removed from being visible in any of the portals, and

3DT are immediately notified. At which time 3DT will review the Misconduct report as well as the


www.3dtgroup.com

Incident in reference. If 3DT agree that that incident in question does in fact meet the 3DT misconduct

rules, that incident will be removed immediately. If 3DT feel that that incident meets the 3DT incident

reporting rules, that incident will be brought back into the list of displayed incidents. The Misconduct

Reporter can elect to be communicated with, and if so before making that incident available, that user

will be communicated with.

Add Incident (Option1: use predefined Incident Input Screen) This API requires only requires your unique “Key Code”, and allows Incidents to be added to the

platform.

To run this API: https://secure.911sa.co.za/reports/V8/addIncident/index.php?keyCode=[your unique Key Code]

Example

Add Incident API (option2) Here the integrator/developer will call the API createIncident, passing various parameters as listed

below:

Parameter Comments Mandatory Example

keyCode Unique to each integrator/developer

Yes keyCode= 43c5f9ed667fe775


www.3dtgroup.com

incidentDate YYYYmmdd hh:mm:ss Yes incidentDate=20160221 11:15:22 expirationDate YYYYmmdd hh:mm:ss

(see note 2 below) expirationDate=20160221 18:00:00

incidentCode See list of incident codes

Yes incidentCode= 100019

details Description of the incident

Yes details=Road closed due to fallen trees

latitude Only required if complete address is not entered

latitude= -26.1075663

longitude Only required if complete address is not entered

longitude=28.0567007

address Only required if latitude and longitude are not entered

address=123 Rivonia road

city Only required if latitude and longitude are not entered

city=Sandton

province Only required if latitude and longitude are not entered

province=Gauteng

country Only required if latitude and longitude are not entered

country=South Africa

postalCode Only required if latitude and longitude are not entered

postalCode=2196

licensePlate Only applicable with specific Incident Codes (see below)

licensePlate=ABC-123-789

OriginalIncidentID If the system supplying the data has its own unique Incident ID, otherwise MUST BE BLANK. If passed and that incident id exists, the existing incident will be updated. If it is unique in the i-Saw

OriginalIncidentID=123abc789


www.3dtgroup.com

system, a new record will be created.

Note 1: All date fields must:-

Follow YYYYmmdd hh:mm:ss format.

Be in the time zone the incident fall under. Example: If the incident being reported is located in Johannesburg Gauteng South Africa, the date and time must be that of the time in Johannesburg Gauteng South Africa.

Note 2: The Expiration Date is not mandatory. If left blank, the system will establish an expiration date based upon the following rules:-

All Incidents that fall under the Category of Traffic, will automatically have an “expirationDate” value equal to the initial incidentDate + 2 hours

All other Incidents the system will automatically set the “expirationDate” value equal to the initial to midnight of the date of the reported incident.

Incident Codes

Status Code Description Category

100013 Abduction Can include License Plate # Crime

100036 Building Fire Crime

100010 Burglary Crime

100012 Carjacking Can include License Plate # Crime

100014 Missing Person Crime

100011 Murder Crime

100028 Radiation In Area Crime

100016 Riot Crime

100015 Shooting Crime

100021 Suspicious Vehicle or Person Can include License Plate # Crime

100000 Terror Alert Crime

100017 Other General

100024 Avalanche Natural Disaster

100003 Earthquake Natural Disaster

100005 Fire Natural Disaster

100004 Floods Natural Disaster

100006 Mud Slide Natural Disaster

100027 Tsunami Natural Disaster

100001 Accident Can include License Plate # Traffic

100022 Congested Traffic Traffic

100041 Disabled Vehicle Traffic


www.3dtgroup.com

100018 Driving Reckless Can include License Plate # Traffic

100026 Fallen Tree Blocking Road Traffic

100025 Falling Rocks Traffic

100031 Potholes or Bad Road Traffic

100020 Power Outage Traffic

100023 Power-line Down Traffic

100042 Protest March Traffic

100019 Road Closed Traffic

100030 Road Construction Traffic

100038 Road Flooded Traffic

100033 Slippery Road Traffic

100032 Traffic Light Not Working Traffic

100034 Vehicle Fire Can include License Plate # Traffic

100037 Water Pipe Broken Traffic

100008 Hail Storm Weather

100029 Heavy Snow Weather

100040 High Winds Weather

100009 Hurricane Weather

100039 Hurricane Weather

100002 Severe Weather Weather

100007 Tornado Weather

Error Codes [result]='Error -> Invalid KeyCode'

[result]='Error -> Incorrect incidentCode'

[result]='Database error'

[result]='Error -> No Location'

Example Create:

https://secure.911sa.co.za/reports/V8/createIncident/index.php?keyCode=[Unique

keyCode]&incidentDate=20160221 2011:15:22&incidentCode=100019&details=Road closed due to

fallen trees&address=123 Rivonia road&city=Sandton&province=Gauteng&country=South

Africa&postalCode=2196&OriginalIncidentID=1234ABC789

Result:

[result]='OK-> Incident # 12345'


www.3dtgroup.com

Edit an Incident (option1: use predefined Incident Input Screen) Incident Address, Comments and additional photos can be updated. The Incident can be Deleted. The Incident Type cannot be changed. This API requires your:

1. Unique “Key Code”, and 2. The “Incident ID” which you wish to edit.

To run this API: https://secure.911sa.co.za/reports/V8/changeIncident/index.php?keyCode=[your unique Key Code]&

id=[incidentID]

Edit an Incident (option2) The following options can be performed using this API.

Append additional detail to the Description of the incident

The Incident can be “Deleted” Here the integrator/developer can call the API editIncident, passing various parameters as listed below:




incidentID This is the Incident # to be edited or deleted

Yes incidentID=112960

detailUpdate This is the flag to Yes detailUpdate=A (to Append comments to the


www.3dtgroup.com

advise to either Append (A) or Delete (D)

incident) or detailUpdate=D (to Delete incident)

details Description of the incident

Yes details=Road closed due to fallen trees

Error Codes [result]='Error -> Invalid KeyCode'

[result]='Error -> Incorrect incidentCode'

[result]='Database error'

[result]='Error -> No Location'

Example Append :

https://secure.911sa.co.za/reports/V8/createIncident/index.php?keyCode=[Unique keyCode]&

incidentID=112960&detailUpdate=A&details=Road opened as of 6pm

Result:

[result]='OK’

Delete :

https://secure.911sa.co.za/reports/V8/createIncident/index.php?keyCode=[Unique keyCode]&

incidentID=112960&detailUpdate=D

Result:

[result]='OK’

Request Incident Data This API returns Incident Data in an XML format. The following parameters are mandatory:

Unique “Key Code”

Country Incident data can be request based upon the following parameters:

Province/State/Region

City

Incident Type (must be in its code form, see Incident Codes)


www.3dtgroup.com

As of Date and Time (It must comply with the format YYYY-MM-DD HH:MM:SS example: 2016-05-01 00:00:00). If left empty, Incident having been posted in the last 30 minutes as of the system clock will be returned.

Additional parameters include the number of records you would like to receive back (if left blank all will be returned).




country Yes country=South Africa fromDateTime YYYYmmdd hh:mm:ss fromDateTime=20160221 11:15:22 incidentCode See list of incident

codes incidentCode= 100019

city city=Sandton province province=Gauteng numberOfRecords Number of records

you want returned numberOfRecords=15

Example https://secure.911sa.co.za/reports/V8/ getIncidents/index.php?keyCode=[Unique keyCode]& country=South Africa

<posts>

<post>

<id>118318</id>

<device_id/>

<datetime>2016-05-13 10:11:43</datetime>

<eventType>100001</eventType>

<eventDescription>Test</eventDescription>

<longitude>28.0473051</longitude>

<latitude>-26.2041028</latitude>

<city>Johansburg</city>

<province>Africa</province>

<areaCode>63773</areaCode>

<address>Johansburg</address>

<country>South Africa</country>

<vehicleRegistration>1237738</vehicleRegistration>

</post>

<post>

<id>118317</id>

<device_id/>

<datetime>2016-05-13 08:16:20</datetime>

<eventType>100014</eventType>

<eventDescription>This is a test with image</eventDescription>

<longitude>28.0593913</longitude>

<latitude>-26.0864981</latitude>

<city>Johannesburg</city>


www.3dtgroup.com

<province>Gauteng</province>

<areaCode/>

<address>164 Rivonia Rd, Sandton, 2057, South Africa</address>

<country>South Africa</country>

<vehicleRegistration/>

</post>

</posts>

i-saw incident manager - 3dt group api.pdf · i-saw is a registered product of 3dt group of...

Documents