Home

Notification API Reference

1. The address contains the path to your assembly Your assembly is responsible to maintain actual device address e string body Formatted packet message This is what you send to the device e bool need_response Indicate if the system requires a response If this flag is true you should send back INCARSP packet once the packet is accepted e int max_delay Maximum delay in seconds is allowed The packet should be discarded if it s not been sent when maximum delay expires e int max_retry Maximum number of attempts allowed Your code shouldn t try more than specified times to send the packet e int retry_interval Interval between two delivery attempts e ref string message A string message you d like to return This message will be saved to Notification Engine log file and displayed on Notification Engine log screen e ref string exp Exception stack trace if there s an exception Compile your assembly and enter the path to this assembly as the device address This assembly is dynamically loaded during message dispatch and will be unloaded afterwards Notification API ReferenceShotSpotter Notification API Version 2 6 docx 39
2. URI 1 Metadata URI n MIME Content Type URI n URI n Metadata Checksum indicator Checksum Message ending root node lt IUPDTO3s gt original incident type final incident type incident workflow status 3 6 Incident Type Codes Two digit incident type codes are now provided for all Generation II packets Incidents may be gunfire fireworks firecrackers or other loud impulsive noise Depending on the workflow status incidents type may be a result of machine classification or human review The following list of incident types defines the entire type space of incidents but it is important to note that Notification API Reference ShotSpotter Notification API Version 2 6 docx SIUPDT03 see IALRT03 Packet above see 3 6 Incident Type Codes see 3 7 Incident Review Workflow Status see IALRT03 Packet above 17 AER Notification API Reference ShotSpotter Notification Engine v2 6 neither automatic machine classification nor human review will necessarily produce all of these incident types nor does SST offer its product for the detection and classification of acoustic events other than gunfire The incident types are provided for data analysis and ease of traceability only Do not rely on incident types other than gunfire being consistently produced Incident Description Gunfire Canonical Dot Type Color in ShotSpotter Code User Interface Software 0 Unclassifie
3. ZOMZ OR OZ OSS OSie ty 0S homo 2540 Giry 5 m93 2012 08 2012 08 05 City0312_27_ 2540 City 277 mp3 https usl shotspotter net City CityAudio For flexibility the Notification Engine allows you to configure a different base URL than is used internally by ShotSpotter software The base URL is configured as a subscription specific property See Subscription Properties ALR T03 only 3 5 IUPDTO3 Packet Like I ALRTO2 IALRTO3 has a companion update packet IUPDT03 which exists to provide incident review workflow updates for subscribers of IALRTO03 packets It duplicates the fields in the IALRTO3 packet and introduces a new Final Incident Type field identifying the final Notification API ReferenceShotSpotter Notification API Version 2 6 docx 16 e S ST 7 classification of an incident i e the classification after the SST Incident Review Center or customer has reviewed the incident audio It also provides an updated workflow status Field Notification API Reference ShotSpotter Notification Engine v2 6 IUPDTO3 Packet Format HTML XML Field Name Sample Length Notes Packet Prefix Incident ID Latitude Longitude Incident Street Address Additional Description Fine grained geofence Coarse grained geofence Source Name Incident Time GMT UTC Offset Original Incident Type Final Reviewed Incident Type Incident Workflow Status URI Count URI 1 MIME Content Type URI 1
4. select INCAUPE time gt name Check gt f gt Note that 1 the Check template is used to compose the checksum string This template can be copied to your style sheet without any change 2 The string CHK is a place holder for check sum When the message is delivered CHK will be replaced with the properly calculated checksum 5 6 2 Composing Your Own XSLT You can use the above example as template to compose your own style sheet If you only want to eliminate some fields to trim down the message you can simply modify the Packet template and remove unwanted fields However in some other cases advanced XSLT authoring skills are required For instance some devices only accept integer values while some others only accept hex number formats The following is an example of a custom XSLT style sheet It translates the INCAUPE message to a 6 letter long string with the first 3 digits representing heading a space and the last 2 digits representing elevation This happens to be the XSLT used to generate the pre defined RMS_INCAUPE format lt xml version 1 0 encoding UTF 8 7S lt xsl stylesheet version 1 0 xmlns xsl http www w3 org 1999 XSL Transform gt lt xsl template match gt lt notifications gt lt Packet gt lt xsl call template name Packet lt Packet gt lt Check gt lt notifications gt lt xsl template gt gt lt xsl template match INCAUPE name
5. INCAUPD 1234 120 00 315 68 0EF r n the string used for checksum calculation equals 1234120 00315 68 Exclusion of delimiters and prefixes ensures that the same packet will get same checksum regardless the protocol used for transportation However if customized formats are used the packet may have a different checksum due to variance in number formats and presented fields The following code in C demonstrates the checksum algorithm We picked a simple algorithm so it can be easily implemented by customers when necessary byte outputData ASCIIEncoding ASCII GetBytes s byte val outputData 0 roe ioe 1 le i lt OUlejoMEDaAica LENGEN arr val outputData i string ret commandPrefix s p Wisi Gering emmer 7 Osx val amp 00 gt gt 4 k nen normat Y O sgxtY wall OsdOi Ae hale Notification API ReferenceShotSpotter Notification API Version 2 6 docx 38 el T Notification API Reference Li ShotSpotter Notification Engine v2 6 Appendix Ill Plug In Architecture You ll need to author a Net assembly that implements the IProtocolBase interface defined in NEP luginInterface d1l which is part of Notification Engine installation The IProtocolBase only contains one method DeliverNotification This method will be called whenever the Notification Engine attempts to send a packet to the device The method has 8 parameters as detailed as following e string address
6. Packet gt lt xsl apply templates select INCAUPE heading lt xsl apply templates select INCAUPE elevation gt gt lt xsl template gt lt xsl template match INCAUPE heading gt lt xsl value of select format number 000 lt xsl template gt ZS lt xsl template match INCAUPE elevation gt lt xsl value of select format number 00 lt xsl template gt lt xsl stylesheet gt f Note that amp 160 is the other the other one is CHK special token in Notification Engine Notification Engine will ensure it gets converted to a valid space ASCII 32 when the messages are sent Notification API Reference ShotSpotter Notification API Version 2 6 docx 27 el T TM Notification API Reference L J ShotSpotter Notification Engine v2 6 5 6 3 An extended example XSLT style sheets may get very complex and may require serious debugging Try your style sheet outside Notification Engine first before you plug it into Notification Engine The following example is the style sheet used to generate SONY_INCAUPE format lt xml version 1 0 encoding UTF 8 gt lt xsl stylesheet version 1 0 xmlns xsl http www w3 org 1999 XSL Transform gt lt xsl template match gt lt notifications gt lt Packet gt lt xsl call template name Packet gt lt Packet gt lt Check gt lt xsl call template name Check gt lt Check gt lt notifications gt lt xsl template gt l
7. API C2 Channel Classification Client Software COP Database Device Device Type Final Classification Notification API Reference ShotSpotter Notification API Version 2 6 docx Notification API Reference ShotSpotter Notification Engine v2 6 Software used by ShotSpotter Flex customers to learn about new incidents in near real time The Alert Console is delivered as an out of browser OOB Silverlight application Application Programming Interface a protocol intended to be used as an interface by software components to communicate with each other Command and Control The delivery mechanism of a notification packet Notification Engine 2 6 supports HTTP GET query string HTTP POST XML payload Socket Google Earth and customer plug in channels The determination of the causative nature of an acoustic event e g Multiple Gunshots Fireworks or Transformer Explosion SST s own user interface software available in two forms the PSC Public Safety Console and the cloud based Flex Alert Console for real time notifications and Incident amp Reports Portal for investigation analysis and reporting Common Operating Picture a system designed to integrated data from disparate sensor surveillance or tracking systems and represent them in a unified view commonly graphically displayed on a map The historical archive of ShotSpotter incidents maintained by the ShotSpotter Server An endpoint which rece
8. Incident Type Codes locations location y time checksum 2234556 4559696 2012 10 16 12300827 OE r n 2 X Y coordinates represents the incident location in the local UTM geographic coordinate system UTM zone must be inferred from system location A convenient UTM lookup tool is provided by APSalin at www apsalin com utm zone finder aspx 4 5 WGSAUPD Packet Deprecated Component HTML XML Sample Field Name Packet Prefix prefix SWGSAUPD Sensor ID id 1234 Sensor Distance in meters distance 120 00 Sensor Heading in degrees heading 315 68 Heading Adjusted heading adjusted 300 68 Elevation in degrees elevation 150 Elevation Adjusted elevation adjusted 10 0 Checksum indicator Checksum checksum OF Message ending r n Notes 1 Zoom is reserved for future use Notification API ReferenceShotSpotter Notification API Version 2 6 docx 21 GASCIR 4 6 WGSIUPD packet Deprecated Notification API Reference ShotSpotter Notification Engine v2 6 Component HTML XML Sample Field Name Packet Prefix prefix SWGSIUPD Sensor ID id 1234 Sensor Friendly Number riendly number 1234 Sensor Friendly Name riendly name Sensor A Sensor Type type 1 Sensor Latitude latitude 33 7890 Sensor Longitude longitude ORAA Sensor Status snr 1 Checksum indicator e Checksum checksum OF Message ending Van Notes 1 Values for the Status field 0 OK 1 O
9. format for the delivery channel If a custom XSLT style sheet is defined Notification Engine will use customized style sheet instead of the default style sheet The following XML is an example of default packet format Each packet is an XML segment with the packet prefix opcode as root node and all supported fields as direct children of the root node Default INCAUPE message in original XML format lt INCAUPE gt Notification API ReferenceShotSpotter Notification API Version 2 6 docx 25 Notification API Reference ShotSpotter Notification Engine v2 6 el Notification API Reference Li ShotSpotter Notification Engine v2 6 lt id gt Incident Id integer lt id gt lt distance gt Incident distance from device number lt distance gt lt heading gt Calcuated device heading degrees from North lt heading gt lt heading adjusted gt Adjusted device heading heading device default heading lt heading adjusted gt lt elevation gt Calcuated device elevation degrees from Horizon lt elevation gt lt elevation adjusted gt Adjusted device elevation elevation device default elevation lt elevation adjusted gt lt zoom gt NOT SUPPORTED lt zoom gt lt time gt Incident time yyyy MM dd HH mm ss lt time gt lt INCAUPE gt The following XML shows how the packet looks like after XSLT transformation The transformed message is also an XML segment with lt notifications gt as root element and two children lt Pack
10. radius generally 100 200 meters around a single sensor and which must have a clear line of sight the moment a gun is fired in order to provide useful information SST s wide area acoustic surveillance technology detects and precisely locates incidents that occur anywhere within a large outdoor coverage area extending many square miles in size regardless of visibility and at distances as far as a mile or more distant from individual sensors Thus a single gunfire incident is often heard by many sensors some of them at the right time based on direct path transit of the sound and some of them at wrong times due to echoes multipath or other delays Subsequent to sound detection by the sensors the technical superiority of the ShotSpotter approach becomes evident as the server software disambiguates the location from the many true and some not true or echo multipath data points provided by the sensor network Among many possible mathematical solutions it finds the optimal one eliminates errors calculates the total number of rounds fired even when one or more rounds cannot be heard on several sensors and the speed and direction of travel of a moving source if applicable and reports these data Single sensor point solutions do not benefit either from the wide area multi sensor redundancy or from the opportunity to compare data on multiple sensors to filter out echoes delays or multipath After the ShotSpotter server per
11. same field types as the Generation I INCAUPD packet but now provides Incident Type explicitly as well as Incident Review Workflow Status Notification API ReferenceShotSpotter Notification API Version 2 6 docx 9 el T D Notification API Reference L J ShotSpotter Notification Engine v2 6 IALRTO1 Packet Format Field HTML XML Sample Length Notes Field Name Packet Prefix root node lt IALRTO1 gt SIALRTO1 see note below Incident ID id 0001234 7 characters Incident Distance distance 00120 00 8 characters meters Incident Heading heading 00315 68 8 characters decimal degrees Incident Type incident type 01 see 3 6 Incident Type Codes Incident Worflow incident workflow see 3 7 Incident Review Status status Workflow Status Checksum indicator Checksum checksum E see Error Not a valid result for table n a Message ending n a Notes 1 The packet prefix begins with a character in ASCII stream format the default for the socket channel In other channels there is no character and the prefix is simply the 7 character prefix 2 These fields contain values relative to the latitude and longitude properties i e the position of the endpoint assigned to individual end points using subscription properties in Notification Engine user interface provided for the camera or endpoint as described in 6 2 Subscription Properties INCAUPE INCAUPD IALRT01 and IALR T02 If no such posit
12. space ASCII code 32 The last two characters represent elevation angle in whole degrees from 00 to 90 Example 312 46 5 7 2 SONY_INCAUPE This format is designed specifically for SONY SNC RZ25N P cameras It generates a Pan Tilt Zoom Focus command according to SONY s specification and sends it to the designated CGI program The three values passed in the command are pan tilt and speed 24 being the maximum speed Example ptzf cgi AbsolutePanTilt 0 0 24 Thus the address of your subscription should be the URL where the ptzf cgi is located with trailing 5 7 3 PDA_INCIUPD This is a simplified INCAUPD format with only incident id incident type incident latitude and incident longitude included It doesn t include a checksum Example SINCIUPD 1027 1 38 85962 76 98861 6 Subscription parameters for different packets Different packets require different sets of parameters These parameters need to be set correctly in your subscriptions in order for Notification Engine to populate the fields of the output packets correctly Some protocols may support only one or several of all possible packets and some specific hardware software only works with specific device type subscription combinations You can change parameters of subscriptions at any time A subscription can be individually enabled or disabled as well However if the device is disabled all its subscriptions are automatically disabled as
13. state 1 4 ShotSpotter Notification API For the purposes of notification to external systems it is important to remember that the wide area distributed nature of a ShotSpotter gunfire alert and analysis solution means that more than one sensor will hear a given gunfire incident but none of the sensors has sufficient information on its own to locate the incident For a notification to be useful therefore it must come from the analysis of multiple sensors data by the ShotSpotter server not from an individual sensor Accordingly the ShotSpotter Notification API is designed to notify external systems when the server reports a new incident This is consistent with the way SST s own ShotSpotter user interface software works but it can cause some confusion for those familiar with other sensor based surveillance systems which send signals from the edges of the network The ShotSpotter Notification API can report new incidents or updated information about incidents previously reported As its name suggests the design of the Notification API focuses heavily on notification of new or recently updated incidents and not on making historical data available for analysis see Historical Data below for more information about how to access historical ShotSpotter incident data Reviewed and unreviewed raw alerts follow slightly different notification workflows as depicted in the following diagram Notification API ReferenceShotSpotter Notific
14. 2 6 of the ShotSpotter Notification API continues support for the Generation I Legacy packet formats introduced in the API versions which shipped with Notification Engine 1 0 and 2 x versions prior to 2 6 41 Important Use Generation Il Packets for All New Projects Transition Away from Generation on Existing Projects in Your Next Rebuild Although Version 2 6 of the Notification API continues to support the Generation I packets originally supported by earlier versions to the extent technically possible changes to both the core ShotSpotter product and improvements to the depth and content of the API will not be mirrored in the Generation I packets and future support for Generation I packets is not guaranteed For new projects use only Generation II For existing projects you should switch to Generation II packets as soon as possible ideally in your next project rebuild Several Generation II packets have intentionally been designed to be backwards compatible with the Generation I packets and thus any revisions to existing projects should make the minimal effort to switch from Generation I to Generation II 4 2 INCAUPD Packet This is a legacy Generation I packet type Its use is supported but deprecated in Notification API versions 2 6 and later The Generation II packet IALRTO1 can be used as a replacement for this packet with minimal required code changes Component HTML XML Sample Field Name Packet Prefix prefix SINCAUP
15. 20 VOSS 00300 OLS 610 010 0 01 00 2012 10 16 OO300227 08 oI hooter moving see note below 7 characters see note below reverse geocoded address see note below see note below the name of the ShotSpotter Database which corresponds to the coverage area 8 characters meters 8 characters decimal degrees 8 characters decimal degrees 5 characters decimal degrees 5 characters decimal degrees 4 characters reserved for future use Local database time NOT UTC 3 characters time zone offset from GMT see 3 6 Incident Type Codes see 3 7 Incident Review Workflow Status see Error Not a valid result for table 11 ei T m Notification API Reference J ShotSpotter Notification Engine v2 6 1 The packet prefix begins with a character in ASCII stream format the default for the socket channel In other channels there is no character and the field contains just the 7 character prefix 2 Please remember that the latitude longitude and other geographic coordinates provided represent the location of the incident itself and explicitly not the coordinates of the sensors reporting the incident This has been the source of confusion for some integrators more accustomed to sensor focused surveillance mechanisms 3 For ShotSpotter OnSite systems reverse geocoding is performed against a customer provided parcel map or address point map For ShotSpotter Flex systems revers
16. 23 el T m Notification API Reference L J ShotSpotter Notification Engine v2 6 5 1 HTTP POST XML payload Channel The preferred delivery format for sending packets is XML as it permits full fidelity and is easy to inspect visually XML is the default payload format for the HTTP POST channel which transmits the data packet in the format of a regular HTTP POST request method Here is a sample of an INCIUPD packet formatted as an XML payload lt INCIUPD gt lt id gt 1053 lt id gt lt latitude gt 38 85962 lt latitude gt lt longitude gt 76 98861 lt longitude gt lt type gt 1 lt type gt lt address gt 303 Second Street lt address gt lt location x gt 0 lt location x gt tlocation yr0 lt location y gt lt time gt 2012 10 18 14 00 36 lt time gt lt INCIUPD gt Note that unlike the ASCII stream formatting for socket channel packets there are no start and checksum delimiting characters and respectively 5 2 HTTP GET query string Channel In the HTTP GET query string channel the data packet is in the format of a regular HTTP request GET string with the field values provided as query string parameters All field names are in lowercases Here is a sample of an INCAUPD packet formatted as a query string prefix INCAUPD amp id 1234 amp distance 120 00 amp checksum 0E The above packet might be sent to a listening URL as a standard HTTP request for example ht
17. D Incident ID id 1234 Incident Distance in meters distance 120 00 Incident Heading in degrees heading 31568 Checksum indicator Checksum checksum OE Message ending r n Notification API ReferenceShotSpotter Notification API Version 2 6 docx 19 GASCIR 4 3 INCAUPE Packet Deprecated Notification API Reference ShotSpotter Notification Engine v2 6 Component HTML XML Sample Field Name Packet Prefix prefix SINCAUPE Incident ID id 1234 Incident Distance in meters distance 120 00 Incident Heading in degrees heading 315 68 Heading Adjusted heading adjusted 300 68 Elevation in degrees elevation 150 Elevation Adjusted elevation MOMO adjusted Zoom zoom il Incident Time time 2012S o gt ik LAS00827 Checksum indicator i Checksum checksum OE Message ending r n Notes 1 Zoom is reserved for future use 4 4 INCIuPD Packet Deprecated Notification API ReferenceShotSpotter Notification API Version 2 6 docx GASCIR Notification API Reference ShotSpotter Notification Engine v2 6 Component HTML XML Sample Field Name Packet Prefix prefix SINCIUPD Incident ID id 1234 Incident Latitude latitude 37 1234 Incident Longitude longitude 120 1234 Incident Type type 1 Incident Address address 303 Second Street Incident Location X Incident Location Y Incident Time Checksum indicator Checksum Message ending Notes 1 see 3 6
18. Notification API Reference Notification Engine version 2 6 ShotSpotter Le P ull veer Copyright 2012 SST Inc All rights reserved ShotSpotter Flex ShotSpotter OnSite ShotSpotter SpecialOps ShotSpotter ShotSpotter Gunshot Location System and the ShotSpotter logo are trademarks of SST Inc SST and ShotSpotter technology is protected by one or more issued U S and foreign patents with other domestic and foreign patents pending Notification API Reference ShotSpotter Notification API Version 2 6 docx el S ST m Notification API Reference L J ShotSpotter Notification Engine v2 6 Table of Contents 1 T chnic l Back Grog H 3 LI Wide Area Acoustic S airy cmc ssiri esia iea a EE eas idveshoers 3 1 2 Incident Review and Eege 4 1 3 Reviewed versus Unreviewed Raw Alerts cc dcocccsnocecimexenasannnssdaxewsastanewnasbantense 4 1 4 ShotSpotter Notification API eene 5 1 5 About Notification EE 6 1 6 Accessing Historical Shots potter Data icccs csskcsecessnstessaasneasdseccasessaadenes cpeienecauaieactenes 7 2 Packet Formats Two Generations ees SEENEN ERC SENSEhAN REESEN 7 2 1 Important Use Generation II Packets for All New Projects cicicisniessnensissseendiensis 7 22 Inventory of Packet Types xyscscdcaicrcatenssccrteieiec ecient at TE E TEPE EEEE 8 2 2 1 Notification E 8 222 e KE 8 3 Generation II Fully Supported Packet Format 8 Sek TALRTOL Us lt r ee ne e
19. Root The root URI to be prepended to all URIs in the packet The URL is constructed from a base URL component which includes the protocol indicator fully qualified domain name FQDN of the host and root path and a variable URL component which changes on an incident by incident basis This property sets the protocol base URL component and must provide the protocol indicator http or https FQDN of the host and whatever root invariant path is required For example a base URL might be https usl shotspotter net City CityAudio 6 5 Subscription Properties INDAUPE in addition to INCAUPE Property Name Comment Device Location Feed This property replaces Device Default Heading Device Latitude and Device Longitude properties in INCAUPE Instead of static values device location and heading will be read from designated sensor specified in this property Send Only When Online When this property is set to Yes 1 the packet is only sent when the sensor status is Online Notification API ReferenceShotSpotter Notification API Version 2 6 docx 31 el S ST TM Notification API Reference L J ShotSpotter Notification Engine v2 6 Send Only When Not Down When this property is set to Yes 1 the packet is only sent when the sensor status is not Down Notification API ReferenceShotSpotter Notification API Version 2 6 docx 32 0 SST L al Appendix l Glossary Alert Console
20. ShotSpotter Notification API Version 2 6 docx 4 el D Notification API Reference L J ShotSpotter Notification Engine v2 6 2 By contrast high cost to respond assets such as police officers or the creation of a CAD Computer Aided Dispatch record or the triggering of a Common Operating Picture COP system are typically notified only of reviewed alerts There are several other differences between the two classes of notifications Unreviewed Raw Reviewed Classification Machine only Machine Reviewer Other Situational Context None Provided when available Timing lt 1 second after location SLA 90 within 60 seconds of receipt of data average lt 20 seconds Notification Appropriate for Relatively low cost to respond Relatively high cost to fast response lt 10 seconds respond slower response gt 10 actions seconds actions e PTZ Cameras e Officer or first responder e DVR timestamp tagging dispatch e UAV look at target camera e CAD record creation slew e Air helicopter asset mission e Other Sensor triggering e UAV fly to target Typical Daily Volumes Hundreds Tens Peak Volumes holidays Thousands Hundreds Updates Sent by ShotSpotter Review None Supported in Notification Engine 2 0 2 6 version Recipients of unreviewed alerts can optionally also subscribe to update notifications which provide information about the subsequent review of an incident previously notified in its unreviewed
21. ace provided for the camera or endpoint as described in 6 2 Subscription Properties INCAUPE INCAUPD IALRT01 and IALRTO2 and in 6 3 Subscription Properties INCAUPE and IALR T02 only If no such position is provided then the values of these fields are undefined 7 Incident distance heading and elevation angle are calculated using three dimensional trigonometric calculations and based on the physical position of the endpoint If your application requires only a 2D pan azimuth angle range without elevation angle solution you should subscribe to the IALRTO1 packet instead Notification API Reference ShotSpotter Notification API Version 2 6 docx 12 el T m Notification API Reference L J ShotSpotter Notification Engine v2 6 3 3 IUPDTO02 Packet The IUPDTO2 packet exists to provide incident review workflow updates for subscribers of IALRT02 packets It duplicates most of the fields in the IALRTO2 packet and introduces a new Final Incident Type field identifying the final classification of an incident i e the classification after the SST Incident Review Center or customer has reviewed the incident audio It also provides an updated workflow status IUPDTO2 Packet Format HTML XML Sample Length Notes Field Name Packet Prefix root node SIUPDT02 see note for IALRTO2 above lt IUPDTO2 gt Incident ID Latitude Longitude Incident Street Address Additional Description Fine grained geofence Coars
22. arth overlay file kml so that incidents can be displayed in Google Earth environment when they are available A specific GoogleEarth_INCIUPD pre defined format has been created for this purpose For additional information see the Google Earth predefined section below and the Notification Engine User s Manual 5 5 Plug In Channel The packets are kept in their original XML format when the plug in channel is used Each packet has its packet type as its root element and support fields as direct children of the root For example INCIUPD in its original format looks like lt INCIUPD gt lt id gt 1053 lt id gt lt latitude gt 38 85962 lt latitude gt lt longitude gt 76 98861 lt longitude gt lt type gt 1 lt type gt lt address gt 303 Second Street lt address gt lt location x gt 0 lt location x gt lt lecat ton y gt 0 lt location y gt lt time gt 2012 10 18 14 00 36 lt time gt lt INCIUPD gt For information regarding how to develop Notification Engine plug in DLLs see Appendix III Plug In Architecture 5 6 Custom formats Notification Engine provides a default format for each of the message types and channels it supports However you can override the default format by authoring a custom XSLT style sheet The original incident data from Notification Engine is in XML format Notification use pre defined XSLT style sheets to translate the XML document to specific
23. ation API Version 2 6 docx 5 Notification API Reference ShotSpotter Notification Engine v2 6 SST Unreviewed Raw Notifications sound of acoustic pulses reach server aggregates sensor SST Incident Review Center gunfire trigger sensors data geolocates source reviews incident Reviewed Alerts Notifications 1 5 About Notification Engine Incident by incident notification is performed by a software component called the ShotSpotter Notification Engine The Notification Engine runs on most modern Microsoft Windows operating systems and 1 polls for new ShotSpotter incidents 2 filters new incidents by type gunfire firework etc and workflow stage unreviewed reviewed 3 notifies multiple subscribers of multiple types by sending one or more message packets 4 receives confirmation of receipt if desired and retries if configured to do so The current version of the Notification Engine is 2 6 It delivers substantial upgrades over previous versions In the table below capabilities new since prior versions are highlighted in blue Incident Workflow Status Unreviewed Alerts Reviewed Alerts Reviewed Updates to Unreviewed Alerts Single Gunfire Multiple Gunfire Possible Gunfire Firecracker Fireworks Backfires Others Incident Types 9 Generation I Packets 5 Generation II Advanced Packets Packet Types Geospatial Boundary Awareness geofences Street Address Lookup Reverse Geoco
24. ccurate results Notification API ReferenceShotSpotter Notification API Version 2 6 docx 30 GAS Device Longitude Device Working Range Flip Heading Angle Flip Elevation Angle M Notification API Reference ShotSpotter Notification Engine v2 6 Decimal Longitude of device 6 digits after decimal point are required for accurate results Effective range of device If the incident is detected out of specified range in meters the device won t get notified Enter 1 for infinite range Indicates whether heading angle should be flipped O No 1 yes Indicates whether elevation angle should be flipped 0O No 1 yes 6 3 Subscription Properties INCAUPE and IALRTO2 only Property Name Comment Device Default Heading Device Default Elevation Device Minimum Zoom Device Maximum Zoom Device Mounted Height The angle in degrees from North that the device faces at its initial idle state The angle in degrees from horizon below that the device faces at its initial ideal state Minimum zoom factor allowed by the device This setting is NOT supported in current version Maximum zoom factor allowed by the device This setting is NOT supported in current version The height of the device In current version all incidents are considered to happen at ground level This value is used to calculate the elevation angle of the device 6 4 Subscription Properties IALRTO03 only Property Name Comment URL
25. d blue 1 Single Gunshot Yes red 2 Multiple Gunshots Yes red 3 Firecracker yellow or white 4 Bottle Rocket yellow or white 5 Aircraft purple 6 Other lime 7 System Test pale green 8 Backfire orange 9 Helicopter purple 10 Motorcycle purple 11 Construction blue 12 Sonic Boom blue 13 Transformer lime 14 Explosion lime 15 Thunder fuchsia 16 Rain fuchsia 17 Firing Test Yes pale green 18 Simulation pale green 19 Possible Gunshot Yes half red half yellow or half red half white 20 Anticipated Gunshot Yes orange 21 Friendly Force Gunshot Yes blue 3 7 Incident Review Workflow Status Incident alerts and incident updates now provide status information regarding the stage progress along the review workflow Referring back to the figure in 1 5 ShotSpotter Notification API the status codes are three letter values defining whether an incident is UNReview REViewed or has been Published automatically due to a Time Out Additional values are reserved for future use in the API but are not currently output by the Notification Engine Review Workflow Status Description UNR REV PTO SPT CHT CMT Notification API Reference ShotSpotter Notification API Version 2 6 docx Unreviewed Reviewed Published due to timeout rare reserved for future use 18 T Wal Notification API Reference ShotSpotter Notification Engine v2 6 REP RCL RLT FRP OTH 4 Generation I Legacy Packet Formats Version
26. ded for future support and expansion An impulse noise adj impulsive noise is one which is both sharp goes from quiet to loud almost instantaneously and commonly wide band in nature The general category includes explosions clicks pops and other such noises A sequence of one or more gunfire sounds or other loud noises detected by either a ShotSpotter OnSite or ShotSpotter Flex sensor network An incident is commonly associated with the shots fired from a single weapon but occasionally involves multiple weapons fired near each other within a few seconds At times an incident may involve a sufficient number of rounds or continue for a long enough period of time that multiple incidents will be generated each covering a different portion of the shooting Software used by ShotSpotter Flex customers to search for prior incidents investigate individual incident timelines or assess trends and patterns Search results can be exported for analysis in third party applications The Incidents amp Reports Portal is delivered as an out of browser OOB Silverlight application The act of listening to audio from a given incident reviewing other situational information e g geography other recent incidents etc and appending such information to the incident record for use by subsequent users of the alert The 24x7x365 monitoring facility maintained by SST Inc which reviews customer incidents for all ShotSpotter Flex and some Sho
27. ding Notification API ReferenceShotSpotter Notification API Version 2 6 docx Two levels of customizable geographic boundaries reported for each incident Parcel map address point or Bing maps web service el S ST m Notification API Reference L J ShotSpotter Notification Engine v2 6 Operating System Support 32 bit Windows XP Windows 7 Windows Server 2003 2008 64 bit Windows 7 Windows Server 2008 Windows Server 2008 R2 Windows Server 2012 beta ShotSpotter Product Support ShotSpotter OnSite ShotSpotter Flex ShotSpotter SpecialOps ShotSpotter CIKR Transport Channels HTTP POST XML payload HTTP GET query string Socket Google Earth KML Plugin d11 Payload Encoding ASCII stream HTTP query string key value XML 1 6 Accessing Historical ShotSpotter Data The ShotSpotter Notification API and its implementation in the ShotSpotter Notification Engine provides real time incident alerts to multiple endpoints They specifically are not designed to provide access to long term aggregated data or statistics Although the endpoints are free to keep their own historical records of incidents e g as a CAD or COP system might SST Inc also offers access to its historical data to customers via both its user interface software and via database APIs The ShotSpotter Flex Incident amp Reports Portal for example can export data meeting any of various search criteria to Microsoft Excel or CSV format For additional info
28. e geocoding is attempted first against the customer provided parcel map or address point map if it exists and provides a valid answer and then subsequently as a fallback mechanism against the Microsoft Bing Maps reverse geocoding web service If the customer parcel or address point map exists but a suitable value is not found during the lookup the Flex server will attempt to reverse geocode the coordinates using Microsoft Bing Maps 4 For ShotSpotter Flex customers the Additional Description field may contain additional information and situational context provided by the SST Incident Review Center Such additional information commonly includes number of rounds fired in cases of multiple gunfire and the speed and direction of travel if the server was able to detect movement among multiple gunshots 5 Fine grained and coarse grained geofences often used for beats and districts respectively can be set up on the ShotSpotter server to permit customers to resolve incidents within fine grained or coarse grained geographic boundaries within their coverage area The terms beat and district are arbitrary but provide some insight into the uses to which these two levels of boundaries geofences are commonly put 6 These fields contain values relative to the latitude longitude and height properties De the position of the endpoint assigned to individual end points using subscription properties in Notification Engine user interf
29. e eee eer eee rae eee ee Meee ee ere 9 ae WE AO cee cs ee ee eee eee eee eee eee ee eee eee re 10 39 UBD TU Packer asian een ai eee 13 etc TAMIR S Eeer ee eg 13 es aM Variable Length EE ee 14 3 4 2 Availability of Audio leg enger gereege ad eetea ac eee 14 3 4 3 IALRTO3 Packet Format eege RER 15 3 gt EE Ee eg 16 3 6 Incident Type Codes geneet 17 3 7 Incident Review TEE 18 4 Generation I Legacy Packet Formats Deprecated EEN 19 4 1 Important Use Generation II Packets for All New Projects Transition Away from Generation I on Existing Projects in Your Next Rebuild eec i eeeeeeeeeeeeeeeeeenneeerees 19 42 JNCAUPD Packet Deprecated eege ege gea 19 4 3 INCAUPE Packet Deprecated scicsceicisse tier uicetadidereh nee nena eee 20 4 4 NGTUPD Packer Deprecated itsi nte ooa en EEE E 20 45 WGSAUPD Packet Deprecated cccccaccestse ctenscestvneceatvesetatvastennienctasebereteereceties 21 4 6 WGSIUPD packet Deprecated icceiciccevaiceceteisdevetetuncet tdcay ai atansvatetcieuatatnecveteteceees 22 4 7 WGSPAIR packet Deprecated lt scecq cueseegetvebiagaivaceedadvetgesaivahededvavietadenereutealguetens 23 4 8 Response packet INCARSP Deprecated saci sccsesccasoncossvaneneesvarenesterieroedenexocten 29 5 Delivery Channels and Formats eegeeegENEKEREEEESESEESEEEEE ENEE EENS NR 23 5 1 HTTP POST XML payload e yaoi sana create snctencieandensesecitdeastacenstemiererenys 24 TO Notification API Reference ShotSpotter Notification Engi
30. e grained geofence Source Name Incident Distance Incident Heading Heading Adjusted Elevation Elevation Adjusted Zoom Original Incident Type original incident type Final Reviewed Incident Type final incident type Incident Worflow Status incident see IALRTO2 above see 3 6 Incident Type Codes see 3 7 Incident Review kflow ee Workflow Status Status Checksum indicator Checksum see IALRTO2 above Message ending 3 4 IALRTO3 Packet The IALRTO3 packet marks a departure from Generation I packets and from their IALRTO1 and IALRTO2 Generation II counterparts The IALRTO3 packet delivers nearly all the incident data available for a given ShotSpotter incident and would be appropriate for use in Common Operating Picture COP or Command and Control C2 systems which seek to aggregate sensor data from multiple platforms In addition to the data provided within the packet it will Notification API ReferenceShotSpotter Notification API Version 2 6 docx 13 el D Notification API Reference L J ShotSpotter Notification Engine v2 6 contain one or more URIs uniform resource identifiers pointing to additional multimedia content available relating to the incident In version 2 6 of the Notification Engine URLs for all sensor audio automatically downloaded are provided Future versions of the ShotSpotter platform may provide additional resources and add additional URIs Each URI includes metadata d
31. es and a given packet type may be transmitted to one or more devices the process of determining the location of a point by measuring angles to it from known points at either end of a fixed baseline rather than measuring distances to the point directly trilateration The point can then be fixed as the third point of a triangle with one known side and two known angles See Reviewed versus Unreviewed Raw Alerts above the surveillance of a large area commonly many square miles for specific acoustic events e g gunfire or explosions Notification API ReferenceShotSpotter Notification API Version 2 6 docx 37 el T m Notification API Reference L J ShotSpotter Notification Engine v2 6 Appendix Il Checksum Calculation Algorithm 1 HTTP Protocol When calculating checksum field name equal signs field delimiters amp and prefix field value are EXCLUDED in calculation Following algorithm in C illustrates how the algorithm works The input variable s is the packet body For example for packet prefix INCAUPD amp id 1234 distance 120 00 amp heading 315 68 amp checks um 0E the string used for checksum calculation equals 1234120 00315 68 2 Socket Protocol When calculating checksum command prefix command ending commas and checksum indicator the sign are EXCLUDED in calculation Following algorithm in C illustrates how the algorithm works The input variable s is the packet body For example for packet Ke
32. escribing the media available at the URI for example Sensor 10 130 meters and the MIME content type for example audio mpeg Because of its intended use primarily as a system to system connector packet and to save room the IALRTO3 packet does not include the relative positioning information heading range elevation which is provided in IALRT02 Relative position makes semantic sense in the context of individual end points such as cameras but makes no sense in the context of other systems e g what is the distance from a CAD system to a gunshot You are not restricted however from subscribing to both packet types but we can imagine few circumstances under which doing so would be appropriate 3 4 1 Variable Length Packet Unlike other packets the IALRTO3 packet has a variable number of fields If there are n URIs included in the packet there will be 14 3n fields not including the checksum indicator or the checksum itself For example if a given incident has four 4 sensor audio files available then the total number of fields in the TALRTO3 packet reporting it will be 14 3 4 26 Similarly an incident with 10 sensor audio files available will have 14 3X10 44 fields 3 4 2 Availability of Audio Files The process of downloading audio files from the ShotSpotter sensor network is handled by the ShotSpotter server software entirely after the incident has been located In order to ensure that alerts are publi
33. et gt and lt Check gt During delivery only the text or XML chunk under lt Packet gt is delivered to destination devices The lt Check gt element is required by system for checksum calculation So when authoring your own custom XSLT you should ensure the transformed message is in the same format as shown below Default INCAUPE message in default HTTP format lt notifications gt lt Packet gt prefix INCAUPES amp id Incident Id integer amp distance I ncident distance from device number amp heading Calcuated device heading degrees from North amp heading adjusted Adjusted device heading heading device default heading amp elevation Calcuated device elevation degrees from Horizon amp elevation adjusted Adjusted device elevation elevation device default elevation amp zoom NOT SUPPORTED amp time I ncident time yyyy MM dd HH mm ss amp checksum check sum of the message lt Packet gt lt Check gt all fields values concated as one single string lt Check gt lt notifications gt 5 6 1 Sample of default XSLT HTTP format As you can see in above sections Notification Engine requires that the default INCAUPE message be transformed into following format anotifications gt lt Packet gt message text to be sent to devices lt Packet gt lt Check gt string used to calculate checksum The string should be composed by concating all values of all fields without names equal signs and delimi
34. eviously ShotSpotter Inc pioneered the concept of Wide Area Acoustic surveillance for gunfire alert and analysis and today has deployed its technologies in over 70 cities worldwide including cities such as Washington D C San Francisco CA Boston MA Chicago IL Rio de Janeiro Brazil Panama City Panama and many others Wide area acoustic surveillance for gunshot detection involves the deployment of multiple collaborative acoustic sensors throughout a coverage area to create a robust redundant coverage array stretching from a single square mile up to 20 or more square miles The sensors are paired with analysis software which identifies the unique signature of gunshots and other loud explosive sounds in real time When a gun is fired the sound it makes the muzzle blast radiates outward at a known velocity the speed of sound and arrives at different ShotSpotter sensors at slightly different times based on each sensor s distance from the origin of the sound Using these slight differences in the time of arrival of the sound the sensors trigger on each impulsive noise they hear mark the precise time and forward that information to the ShotSpotter server software The server software pinpoints the precise location of each round fired by algorithms primarily relying on a combination of multilateration and triangulation In contrast to point protection gunshot detection systems which rely on individual sensors to operate within a small
35. ffline 2 Down 3 Unknown Notification API ReferenceShotSpotter Notification API Version 2 6 docx 22 AER 4 7 WGSPAIR packet Deprecated Notification API Reference ShotSpotter Notification Engine v2 6 Component HTML XML Sample Field Name Packet Prefix prefix SWGSPAIR Sensor ID id 1234 Sensor Latitude latitude 33 7890 Sensor Longitude longitude 120 2424 Sensor Battery Level battery 20 123 Sensor PDOP pdop 0 123 Sensor Bearing bearing 207123 Sensor SNR snr 0 Checksum indicator checksum Checksum prefix OF Message ending id Ze Notes 1 Values for the SNR field will be reported as zero 0 in this version 4 8 Response packet rncarsp Deprecated In response to INCAUPD and INCAUPE packets you may issue an INCARSP packet described below back to the server For details on configuring inbound receipt of packets please see the Users Manual Component HTML XML Sample Field Name Packet Prefix prefix SINCARSP Incident ID id 1234 Acceptance flag A Accepted R flag A Rejected Checksum indicator n a i Checksum checksum 45 Message ending n a r n 5 Delivery Channels and Formats The Notification Engine supports various channels through which packets can be transmitted The packet contents do not change but the formatting and delimiting of the packet fields does change slightly Notification API ReferenceShotSpotter Notification API Version 2 6 docx
36. forms the initial location calculation it turns to the individual pulses shots within the sequence of shots and optimizes its location to produce a final location result Then it uses certain acoustic pulse characteristics metadata to make an initial machine classification of the incident and optionally requests one or more sensors to begin to download an audio recording of the few seconds containing the incident back to the server Note that prior to this download request the entire sequence of events detection location optimization and alert is performed without access to the underlying raw audio stream at the sensor Notification API ReferenceShotSpotter Notification API Version 2 6 docx 3 el T Wi Notification API Reference LJ ShotSpotter Notification Engine v2 6 These initial alert data have not yet been reviewed and are therefore referred to as raw alerts or sometimes more technically as unreviewed alerts Such alerts commonly include some cases of gunfire as well as cases of fireworks and other loud impulsive noises such as explosions Generally speaking these raw alerts are useful in the sense that they indicate that something loud and impulsive in acoustic nature or character originated at a particular geographic location at a particular time In cases where targeting other sensors has relatively low cost as for example nearby pan tilt zoom PTZ controllable video cameras it is often desirable to trigger or notify external sy
37. hat zero degree elevation is precisely parallel to the ground These and other settings are configured in the subscription specific settings for a given end point see 6 2 Subscription Properties INCAUPE INCAUPD IALRT01 and IALRTO2 and 6 3Subscription Properties INCAUPE and IALRT0O2 only Notification API ReferenceShotSpotter Notification API Version 2 6 docx 10 AER Field IALRTO2 Packet Format HTML XML Field Name Notification API Reference ShotSpotter Notification Engine v2 6 Sample Length Notes Packet Prefix Incident ID Latitude Longitude Incident Street Address Additional Description Fine grained geofence Coarse grained geofence Source Name Incident Distance Incident Heading Heading Adjustea Elevation Elevation Adjustea Zoom Incident Time GMT UTC Offset Incident Type Incident Worflow Status Checksum indicator Checksum Message ending Notes root node lt IALRT02 gt id latitude longitude address description beat district source distance heading heading adjusted elevation levation adjusted time gmt offset incident type incident workflow status n a checksum n a Notification API Reference ShotSpotter Notification API Version 2 6 docx SIALRTO2 001234 01 123456 SR Les 6 03 Second erect rounds E no s ES EECH E at Smph 111AAA 222BBB ABCity 001
38. hotSpotter Notification Engine v2 6 e SST 3 4 3 IALRTO3 Packet Format Specification TALRTO3 Packet Format Field HTML XML Field Name Sample Length Notes Packet Prefix Incident ID Latitude Longitude Incident Street Address Additional Description Fine grained geofence Coarse grained geofence Source Name Incident Time GMT UTC Offset Incident Type Incident Worflow Status URI Count URI 1 MIME Content Type URL 1 URI 1 Metadata URI n MIME Content Type URL n URI n Metadata Checksum indicator Checksum Message ending Notification API Reference ShotSpotter Notification API Version 2 6 docx root node lt IALRT03 gt id latitude longitude address description beat district source time gmt offset incident type incident workflow status uri count SIS lt uri detail gt mime url description description lt uri detail gt lt uris gt n a checksum n a SIALRTO3 0001234 SET 012 123456 303 Second Street 7 founds shooter moving SE at 5mph 111AAA 222BBB ABCity 2012 10 16 00700327 08 Ol UNR 05 audio mpeg https usl shotspo tter net City CityAudio 2012 08 2012 08 05 ese Oi sike Gy 2oa CEET Sensor 5 50 meters audio mpeg https usl shotspo tter net City CityAudio 2012 08 2012 08 05 Pemer OSLA 2 aa Saien 1 amps Sensor 27 250 meters see note below 7 characters see note be
39. input of anywhere from two 2 to twenty 20 sensors A network of collaborative sensors deployed over a wide area possibly many square miles which transmit data to a ShotSpotter server No individual sensor locates a gunfire incident but rather many sensors will often trigger in response to a single incident The ShotSpotter server software is solely responsible for managing these multiple triggers and transforming multiple input streams into a single unified view of the acoustic event called a gunfire incident ShotSpotter server software which aggregates acoustic impulse data from many sensors correlates and Notification API ReferenceShotSpotter Notification API Version 2 6 docx 36 SST L all ShotSpotter Flex ShotSpotter Onsite Subscription Triangulation Unreviewed Raw Alert Wide Area Acoustic surveillance Notification API Reference ShotSpotter Notification Engine v2 6 disambiguates the signals and produces a single unified view of individual gunfire incidents in near realtime The subscription based offering of ShotSpotter technology with a cloud based infrastructure and with no up front capital investment required from customers Compare ShotSpotter OnSite A ShotSpotter system sold as capital equipment not on a subscription basis Compare ShotSpotter Flex The binding of a specific Device endpoint to a specific packet message type A Device may subscribe to one or more packet typ
40. ion regarding the incident can accept a geo referenced endpoint and will calculate relative range bearing elevation Extended Alert IALRTO3 Extended detailed alert packet with detailed with information regarding the incident and provides a Multimedia variable number of associated URLs for incident audio URLs audio etc Incident T1UPDT02 Update packet supporting Reviewed Alerts and Update other after detection updates classification change etc Issued to subscribers of I ALRTO2 messages IUPDT03 Update packet supporting Reviewed Alerts and other after detection updates classification change etc Issued to subscribers of ALRTO3 messages In the sections that follow each packet its opcode and its fields and values are provided in detail In most cases the Generation II packet is designed as a superset of a Generation I packet For convenience sections which are new or modified from Generation I to Generation II are highlighted in blue Note that incident IDs have been standardized in Generation II to 7 characters permitting 10 million incident IDs per system they were previously variable length It is not uncommon to see 500 000 or more incidents on busy systems Distances in meters and headings in degrees are now standardized as 5 places before the decimal place and 2 places after 3 1 IALRTO1 Packet The IALRTO1 packet is intended for simple endpoints which cannot manage much data It supports the
41. ion this final state is referred to as the final classification or less commonly the reviewed classification Once incidents have been reviewed the data now called reviewed gunfire alert data are ready for presentation to end users either by SST s own ShotSpotter user interface software or by third party software products which are notified Our own user interface software which displays these data exists in several generations including the PSC Public Safety Console generation for ShotSpotter OnSite systems and the cloud based ShotSpotter Alert Console and Incident amp Reports Portal software for subscription based ShotSpotter Flex customers Gunfire incidents are also permanently archived along with forensic data and actual incident audio recordings for subsequent analysis review during investigation presentation during criminal legal proceedings and long term crime trend analysis 1 3 Reviewed versus Unreviewed Raw Alerts After review and subsequent customer alert many customers seek to have ShotSpotter data automatically transmitted notified to external systems which had not been previously notified of the raw unreviewed alert Thus there are two types of notifications 1 Instantaneous notification of raw unreviewed alerts is appropriate for low cost to respond assets such as PTZ cameras for which the cost of turning in the direction of a sound is negligible Notification API Reference
42. ion is provided then the values of these fields are undefined 3 Incident distance and heading are calculated based on the position of the endpoint as described above using two dimensional trigonometric calculations Ifa 3D pan azimuth angle range heading elevation angle solution is required use the IALRTO2 packet 4 The checksum indicator will appear only in the ASCII stream format the default for the socket channel See Appendix II Checksum Calculation Algorithm 3 2 IALRTO2 Packet The IALRTO2 packet is intended for more capable endpoints which want full incident data but do not intend to reference multimedia resources available by URL request It supports the same field types as the Generation I INCAUPE and INDAUPE packet but now provides Incident Type explicitly Incident Review Workflow Status and information regarding the location of the event with regard to geographic boundary ies specified for the two different geographic boundary geofence layers on the ShotSpotter server commonly referred to as beat layer and jurisdiction layer but which can be used for any similar geofencing purpose Like the Generation I packets INCAUPE and INDAUPE the IALRTO2 packet supports a heading offset and an elevation offset These offsets are useful when cameras are not installed with their internal zero degree direction pointing precisely North or when they are not positioned such t
43. ives one or more packet types to which it is subscribed Device information is stored in the ShotSpotter data along with subscription details Devices can represent real world recipients such as surveillance cameras or computers or virtual entities such as server software endpoints aggregators etc Device Types are pre defined groups that into which you can put one or more Devices Device Type does not affect how the notifications are delivered it is an organization aid only The pre defined Device Types are Surveillance Camera Computer Google Earth and PDA The classification type of an incident selected after a Reviewer has reviewed an incident 33 eo SST L d Final Location Formats Generation I Generation II Impulsive noise Incident Incident amp Reports Portal Incident Review Incident Review Center Notification API Reference ShotSpotter Notification Engine v2 6 The optimized incident location calculated in real time by the ShotSpotter server software The data presentation used by a given subscription Certain channels are limited to certain formats For example HTTP GET will only provide data in the ASCII stream format Formats available are Query String key value XML and ASCII stream The first generation of Notification API packet types introduced in 2006 and now formally deprecated The current generation of Notification API packet types introduced with Version 2 6 and inten
44. low reverse geocoded address see note below see note below the name of the ShotSpotter Database which corresponds to the coverage area Local database time NOT UTC 3 characters time zone offset from GMT see 3 6 Incident Type Codes see 3 7 Incident Review Workflow Status 2 digits total number of URIs URLs following the IANA MIME media type available at this URI see note below see note below see Error Not a valid result for table 15 el T m Notification API Reference L J ShotSpotter Notification Engine v2 6 Notes The packet prefix begins with a character in ASCII stream format the default for the socket channel In other channels there is no character and the field contains just the 7 character prefix Please remember that the latitude longitude and other geographic coordinates provided represent the location of the incident itself and explicitly not the coordinates of the sensors reporting the incident This has been the source of confusion for some integrators more accustomed to sensor focused surveillance mechanisms For ShotSpotter OnSite systems reverse geocoding is performed against a customer provided parcel map or address point map For ShotSpotter Flex systems reverse geocoding is performed first against the customer provided parcel map or address point map if it exists and provides a valid answer and then subsequently as a fallback mechanism against the Mic
45. ne v2 6 5 2 HTTP GET query string Channel g eegente eege eet 24 Bie Socket as ee e 24 5S4 Google EEN 25 Fe Plop Channel E 25 5 6 Custom POMS eege Eege 25 5 6 1 Sample of default XSLT HTTP fomtat s coctcciccctecctecessictacssasecacaediainciapaiecees 26 5 6 2 Composing Your Own XSLT E 21 5 63 Anextend d example esences e n E E E EE E E 28 5 7 Additional Pre Defined EE tree eebe 29 Sa 1 a L RMS e 29 Die be 2 SONY INCAUP Eesen r e E EE EAEE dee 29 Jels PDA TNC EE eenegen AEEA ATEREA E ERER EAEE 29 6 Subscription parameters for different packets EN 29 6 1 Subscription Properties Eent 2zegiefeieeetz n geeint neie Ae EE debeEu Ee 30 6 2 Subscription Properties INCAUPE INCAUPD IALRTO1 and IALRTO2 30 6 3 Subscription Properties INCAUPE and ITALRT02 onbe 31 6 4 Subscription Properties TAURTOS only asi EeCNEEENERREEeCNEEEEeE eEEeEdeEnEdeE 31 6 5 Subscription Properties INDAUPE in addition to INCAUDEI 31 Appendix l Glossaty asics St seinemcdadaa nan E E a EEEa Ea 33 Appendix II Checksum Calculation Algorithm NN 38 Appendix II Plug In Architecture enke KENE ENKEN KENE EE REENEN EE ENEE ENEE ENEE EEN 39 Notification API Reference ShotSpotter Notification API Version 2 6 docx 2 el T m Notification API Reference L J ShotSpotter Notification Engine v2 6 1 Technical Background 1 1 Wide Area Acoustic Surveillance In 1995 SST Inc pr
46. ns are revealed producing a fix The expulsion of gas from the end of the barrel of a gun after it has been fired which creates a high amplitude wide band pressure wave commonly called the bang of the gun firing The act of raising an alert as a result of an incident detection or subsequent updates to its stats The Application Programming Interface defining the characteristics of ShotSpotter incident alert notifications Client side software which performs actual notifications consistent with the Notification API Notifications take the form of message packets The actual content of a notification sent from a Notification Engine instance to one endpoint Specific characteristics of certain endpoints which define them specifically For example there may be many endpoints identified as camera but each will have different latitude and longitude parameters Parameters are often used to customize a message packet for a specific endpoint for example to point a camera in the correct direction relative to that specific camera s location Notification API Reference ShotSpotter Notification API Version 2 6 docx 35 AER Point Protection Raw alert Queue Reclassification Reviewed Alert Reviewed Alert Service Sensor Sensor Network Server Notification API Reference ShotSpotter Notification Engine v2 6 The protection of a relatively small area such as circle of 100 or 200 meters radius aro
47. rmation please refer to Application Note 101 Accessing ShotSpotter Data available from SST Inc 2 Packet Formats Two Generations With Version 2 6 of the ShotSpotter Notification API and Notification Engine SST has introduced a new family of message packets designed for both the ShotSpotter OnSite capital equipment and ShotSpotter Flex subscription products and business models We refer to this new family of message packets as Generation II message packets Message packets supported by earlier API versions are referred to as Generation I message packets el S ST TM Notification API Reference L J ShotSpotter Notification Engine v2 6 the other after making a simple prefix opcode change 22 Inventory of Packet Types 2 2 1 Notification amp Response Generation II Generation I Fully Supported Deprecated Simple Alert TALRTO1 INCAUPD Extended Alert L ALRT02 INCAUPE INDAUPE Extended Alert with Multimedia ALRTO3 n a audio URLs Incident Update T1UPDT02 INCIUPD IUPDT03 Response Packet scheduled for future release INCARSP 2 2 2 Telemetry Telemetry functionality has not been updated for Generation II Due to the 24x7x365 monitoring and support capabilities provided by SST to its customers API based export of sensor telemetry is no longer a requirement and is not scheduled for support or maintenance in the future Generation II Generation I Fully Supported Deprecated Sensor Statu
48. rosoft Bing Maps reverse geocoding web service If the customer parcel or address point map exists but a suitable value is not found during the lookup the Flex server will attempt to reverse geocode the coordinates using Microsoft Bing Maps For ShotSpotter Flex customers the Additional Description field may contain additional information and situational context provided by the SST Incident Review Center Such additional information commonly includes number of rounds fired in cases of multiple gunfire and the speed and direction of travel if the server was able to detect movement among multiple gunshots Fine grained and coarse grained geofences often used for beats and districts respectively can be set up on the ShotSpotter server to permit customers to resolve incidents within fine grained or coarse grained geographic boundaries within their coverage area The terms beat and district are arbitrary but provide some insight into the uses to which these two levels of boundaries geofences are commonly put Internally the audio URL is constructed from a base URL component which includes the protocol indicator FQDN and root path and a variable URL component which changes on an incident by incident basis The variable URL component contains a date hierarchy as well as a sensor and incident specific name The fixed and variable components of the URL examples above are shown here Base URL component Variable component
49. s WGSIUPD Sensor Update no longer supported WGSAUPD Sensor Pair WGSPAIR 3 Generation II Fully Supported Packet Formats The Generation II packet formats provide incident notification alert via the IALRTOx group of packets three of which are introduced with API Version 2 6 To accommodate Incident Review Center or customer premises incident review workflow a new IUPDTOx group of packets is introduced to permit subsequent update to incident information after initial raw alert Developers have often asked for API level access to ShotSpotter sensor audio e g an mp3 recording of the gunfire incident as heard at each sensor plus one to two seconds of audio before and after The new Generation II packet IALRTO3 and IUPDTO3 provide audio URLs to all available sensor audio and are structured to provide support in the future for other multimedia Notification API ReferenceShotSpotter Notification API Version 2 6 docx 8 el Wi Notification API Reference L ShotSpotter Notification Engine v2 6 types including for example aerial imagery of the incident location showing a dot on the map The packet types available are Purpose Message Purpose Packet Prefix Opcode Simple Alert IALRTO1 Basic alert with minimal information to pan tilt zoom devices can accept a geo referenced endpoint and will calculate relative range bearing elevation Extended Alert TALRT02 Detailed alert packet with detailed informat
50. select floor Ssony_value 190 2267 div 170 63270 gt lt xsl call template gt lt xsl when gt lt xsl otherwise gt lt xsl call template name dec_to_hex gt lt xsl with param name value select 0 gt lt xsl call template gt lt xsl otherwise gt lt xsl choose gt lt xsl template gt lt xsl template name dec_to_hex gt lt xsl param name value gt lt xsl if test S value gt 15 gt lt xsl call template name dec_to_hex gt Notification API ReferenceShotSpotter Notification API Version 2 6 docx 28 el Notification API Reference L J shotSpotter Notification Engine v2 6 lt xsl with param name value select floor value div 16 Salta EEN ep Rel bate lt xsl value of select substring hex_digits value mod 16 1 1 gt lt xsl template gt lt xsl stylesheet gt 57 Additional Pre Defined Formats In additional to the default formats some additional formats are predefined in Notification Engine 2 6 To use these formats enter the corresponding Format Key into the Custom Format XSLT field of your subscription Note make sure subscribed packets match the selected pre defined format For instance the RMS_INCAUPE format only applies to INCAUPE packet as the format key makes clear 5 7 1 RMS_INCAUPE This is a very short format with only 6 characters The first 3 characters represent the heading angle in whole degrees from 000 to 359 The fourth character is a
51. shed as quickly as possible an unreviewed alert will be published as soon as the location has been calculated but very often before the audio is available Accordingly your application must make allowances for additional audio download time after the incident has taken place By the time a reviewed alert is published it is nearly always the case that at least one audio file is available on which the SST Incident Review Center has in part based its acoustic analysis However in general external applications should assume that URLs will be valid at some time after an incident is alerted but 1 almost certainly will not be available immediately for unreviewed alerts and 2 may not all be available immediately for reviewed alerts As SST configures the web servers providing audio they will return HTTP standard response code 404 before audio is available and 200 along with the audio data when it is available Thus a simple HTTP polling loop will suffice to deliver audio when it becomes available We recommend you stop polling at some point after alert as it is sometimes the case that audio is expected to be available but for network connectivity or congestion reasons cannot be downloaded 1 URTI is the term describing a superset which includes the more familiar URL uniform resource locator as well as URN uniform resource name Notification API ReferenceShotSpotter Notification API Version 2 6 docx 14 Notification API Reference S
52. stems on the basis of these raw alerts in order to get eyes on target immediately and thus further the investigation Such notifications can be but do not have to be performed immediately and before gunfire is confirmed Thereafter or in parallel a process of incident review begins in order to establish whether the incident in question is indeed gunfire 1 2 Incident Review and Alert The next step is thus incident review For customers of SST s ShotSpotter Flex subscription based service raw incident data are reported directly to the SST Incident Review Center IRC where our Reviewed Alerts Service provides immediate assessment and qualification of gunshot alerts by a highly trained team of SST gunfire and acoustics experts 24x7x365 For customers of SST s ShotSpotter OnSite capital equipment products the Reviewed Alert Service is available as an option or customers can choose to review all the raw incidents themselves Over time most SST customers have chosen to avoid the expense and effort of training their own 24x7x365 staff and now rely on SST s Reviewed Alerts Service SST incident reviewers have quite literally heard more gunfire incidents from a wider variety of distances and acoustic environments than anyone else in the world When their work is complete the incident may or may not have been reclassified i e determined to be of a different type gunfire fireworks etc than the initial machine classificat
53. t xsl template match INCAUPE name Packet gt ptzfi cgi AbsolutePanTilt lt xsl call template name sony_from_360 gt lt xsl iwith param name sony_value select INCAUPE pan gt lt xsl call template gt d lt xsl call template name sony_from_360 gt lt xsl with param name sSony_value select 360 INCAUPE tilt gt lt xsl call template gt 124 lt xsl template gt lt xsl template match INCAUPE name Check gt lt xsl apply templates gt lt xsl template gt lt xsl variable name hex_digits select 0123456789ABCDEFX gt lt xsl template name sony_from_360 gt lt xsl param name sony_value gt lt xsl choose gt lt xsl when test Ssony_value gt 0 and Ssony_value lt 170 gt lt xsl call template name dec_to_hex gt lt xsl with param name value select floor Ssony_value 2267 div 170 gt lt xsl call template gt lt xsl when gt lt xsl when test S sony_value gt 170 and Ssony_value lt 180 gt lt xsl call template name dec_to_hex gt lt xsl with param name value select 2267 gt lt xsl call template gt lt xsl when gt lt xsl when test Ssony_value gt 180 and Ssony_value lt 190 gt lt xsl call template name dec_to_hex gt lt xsl with param name value select 63269 gt lt xsl call template gt lt xsl when gt lt xsl when test sony_value gt 190 and sony_value lt 360 gt lt xsl call template name dec_to_hex gt lt xsl with param name value
54. tSpotter OnSite customers The facility is located in Newark CA Notification API Reference ShotSpotter Notification API Version 2 6 docx 34 AER Initial Machine Classification Initial Location Multilateration Muzzle Blast Notification Notification API Notification Engine Message Packet Parameters Notification API Reference ShotSpotter Notification Engine v2 6 The computer generated initial classification of an incident delivered as part of a raw unreviewed alert The Machine Classifier implements learning algorithms and subsequent reclassification may improve its initial classification accuracy The first location calculation performed by the ShotSpotter server commonly not reported because it is replaced within 1 second by the final location result A term originating in navigation multilateration is a technique based on the measurement of the difference in distance to two or more stations at known locations that broadcast signals at known times Unlike measurements of absolute distance or angle measuring the difference in distance results in an infinite number of locations that satisfy the measurement When these possible locations are plotted they form a hyperbolic curve To locate the exact location along that curve a second measurement is taken to a different pair of stations to produce a second curve which intersects with the first When the two are compared a small number of possible locatio
55. ters lt Check gt lt notifications gt To achieve this transformation Notification uses the following style sheet for its HTTP channel lt xml version 1 0 encoding UTF 8 gt lt xsl stylesheet version 1 0 xmlns xsl http www w3 org 1999 XSL Transform gt lt xsl template match gt lt notifications gt lt Packet gt lt xsl call template name Packet gt lt Packet gt lt Check gt lt xsl call template name Check gt lt Check gt lt notifications gt lt xsl template gt lt xsl template match INCAUPE name Packet gt prefix INCAUPE amp id lt xsl apply templates select INCAUPE id gt amp distance Notification API ReferenceShotSpotter Notification API Version 2 6 docx 26 i GS 7 lt xsl apply templates amp heading lt xsl apply templates amp heading adjusted lt xsl apply templates lt xsl apply templates amp elevation adjusted lt xsl apply templates Ak Zoom lt xsl apply templates amp time lt xsl apply templates amp checksum CHK lt xsl template gt lt xsl template match INCAUPE lt xsl apply templates lt xsl template gt lt xsl stylesheet gt Notification API Reference ShotSpotter Notification Engine v2 6 select INCAUPE distance gt select INCAUPE heading gt select INCAUPE heading adjusted gt amp elevation select INCAUPE elevation gt select INCAUPE elevation adjusted gt select INCAUPE zoom gt
56. tp 192 168 0 1 somepage jsp prefix INCAUPD amp id 1234 dista nc 120 00 amp heading 315 68 amp checksum 0E Note that unlike the ASCII stream formatting for socket channel packets there are no start and checksum delimiting characters and respectively Instead the commonly used key value query string format is relied upon to delimit contents 5 3 Socket TCP Channel In the socket channel packet data is sent as ASCII streams Each data packet starts with a dollar sign character and the 7 character packet prefix and ends with two characters r n carriage return followed by line feed ASCII values 13 and 10 respectively A packet body will usually contain multiple fields separated by comma The last three characters of a packet body is an asterisk sign and a two character checksum The following is a sample of a Generation I INCAUPD packet as it would be transmitted via the socket channel ke INCAUPD 1234 120 00 315 68 0F r n and here is a sample Generation II I ALRTO2 packet Notification API ReferenceShotSpotter Notification API Version 2 6 docx 24 AER SIALRT01 0001234 37 538867 122 064656 303 Second Street 7 rounds shooter moving SE at 5Smph 111AAA 222BBB ABCity 00120 00 315 68 300 68 015 0 010 0 01 00 2012 10 16 12 00 27 08 01 UNR 0E r n 5 4 Google Earth Using the Google Earth device type and GoogleEarth protocol permits users to generate and update a Google E
57. und a given point Contrast Wide Area Acoustic surveillance See Reviewed versus Unreviewed Raw Alerts above For each attached Device Notification Engine maintains a message queue to cache packets The message queue ensures that 1 packets are delivered in the order of occurrence and 2 no packets are lost The act of changing the type of an incident often performed by an Incident Reviewer after listening to the audio recording or otherwise learning of an incident s true nature See Reviewed versus Unreviewed Raw Alerts above The 24x7x365 monitoring service provided by SST Inc to its Flex customers and certain OnSite customers The Reviewed Alert Service is staffed by incident review specialists who have heard thousands of gunfire and non gunfire training incidents The edge device deployed by SST Inc comprising a microphone and on board electronics to process sounds heard by the microphone When the sensor triggers on an impulsive noise it transmits a small datagram to the server detailing certain characteristics of the noise including its sharpness and amplitude In contrast to other sensor based surveillance technologies ShotSpotter sensors are only part of the overall solution The ShotSpotter server coordinates the data streams from multiple sensors aggregates the data disambiguates and optimizes solutions and presents a single unified view of each individual incident Such unified views commonly reflect the
58. w many times the Notification Engine tries to re deliver the message upon previous falure Also you can set up the Max Delay property which decides the maximum time length Notification Engine keeps re delivering The message will be discarded upon expiration of either value The time delay in seconds between delivery attempts The maximum time length Notification Engine should try to re deliver the message See Max Retry Indicate whether the Notification Engine should expect a response from the device The response message has to be in the format of INCARSP which is prefix INCARSP amp id Incident ID amp f1lat Response Flag The Incident ID is the incident id contained in the delivered message and Response Flag can be A I or R If the response flag is A accepted or I Ignored Notification Engine will consider the message delivered If the response flag is R rejected Notification Engine will try to re deliver the message till either Max Retry or Max Delay expires File name of the custom XSLT style sheet The path of custom XSLT style sheets is defined in Custom XSLT Location field in the Settings tab The complete path Notification uses to access the file is Custom XSLT Location Custom Format XSLT 6 2 Subscription Properties INCAUPE INCAUPD IALRTO1 and IALRTO2 Property Name Comment Device Latitude Decimal Latitude of device 6 digits after decimal point are required for a
59. well Notification API ReferenceShotSpotter Notification API Version 2 6 docx 29 el T m Notification API Reference L J ShotSpotter Notification Engine v2 6 6 1 Subscription Properties Common Property Name Comment Enabled Channel Address Max Retry Retry Interval Max Delay Require Response Custom Format XSLT Indicates if the subscription is enabled If a subscription or its associated device is disabled no message is sent Delivery protocol used for this delivery HTTP channel means the messages will be sent as HTTP GET request string Telnet channel means the message will be send as ASCII stream over a socket connection Delivery address For HTTP channels this address should be the web page that accepts the request string The final request string generated by Notification Engine will be of the format Address Message string The message string consists a series of name value pairs in the format of Name Value separated by amp For example in the case of INCAUPE assuming the subscription ishttp 192 168 0 2 index htm the final request string looks like http 192 168 0 2 index htm prefix INCAUPE amp 1id 701 distance 3747239 58885 amp heading 73 39422 amp heading adjusted 73 39422 amp elevation 0 00005 elevation adjusted 0 00005 amp zoom 1 amp time 2012 09 13 14 27 43 amp checksum 06 For telnet this address should be IP address Port number This value decides ho

Notification API Reference

Contents

Download Pdf Manuals

Related Search

Related Contents