Getting Started with AISAP http://ais-portal.usace.army.mil/

Contents AISAP Interface ..................................................................................................................................................... 2

Query Tool ............................................................................................................................................................ 3

First Login .............................................................................................................................................................. 4

Creating Projects ................................................................................................................................................... 4

Setting the data source for a project ................................................................................................................ 5

Setting the default data filters for a project ..................................................................................................... 6

MMSI filter .................................................................................................................................................... 7

Sharing a project ............................................................................................................................................... 7

Creating a duplicate project.............................................................................................................................. 8

Processing all AOIs in a project ......................................................................................................................... 8

Deleting a project.............................................................................................................................................. 8

Creating Areas of Interest ..................................................................................................................................... 9

Adding/Editing AOI Vectors ............................................................................................................................ 10

Inbound Vector ........................................................................................................................................... 10

Velocity Gate ............................................................................................................................................... 10

Channel Center Line .................................................................................................................................... 11

Hiding and showing vectors ............................................................................................................................ 12

Analysis tools in AISAP ........................................................................................................................................ 12

Setting individual AOI filters ........................................................................................................................... 12

Charts and graphs showing analysis results ................................................................................................... 13

Viewing Vessel transits ................................................................................................................................... 13

Heat map Layer ............................................................................................................................................... 14

Cluster Layer ................................................................................................................................................... 15

2

RIS Proxy Service ................................................................................................................................................. 16

Parameters ...................................................................................................................................................... 16

Real Time Webservices ................................................................................................................................... 17

AISAP Interface

AIS Web Console

1. Find Requests – Allows the user to view the data available within selected dates and location. This page also allows the user to set one or more requests as the data source for a project. By default, no data source is selected.

2. Query Tool – Allows the user to request data from the Coast Guard by providing an email address and other filter options to narrow down the data.

3. RIS Proxy Service – Returns data from the database in the format selected. 4. Request Status Lookup – Checks on the status of data requests. 5. Base map - Changes the appearance of the map. The options available are: streets, satellite, hybrid,

topo, gray, oceans, national geographic, osm. 6. Toggle Layers – Allows the user to show/hide river mile markers and AIS site locations. 7. Measure – Toggles the map measurement tools on/off. Use the tool to measure areas and distances,

and determine the coordinates for any location on the map.

1 2

3

4

5 6 7

3

Query Tool

The query tool is accessed from the Data Requests drop down menu. The query tool is used to request AIS reports from the database maintained by the United States Coast Guard (USCG). Each request has two automated calls to the USCG server; the second call begins automatically after the first completes. The first call returns a list of every vessel, and its static information such as width, that passed through a user-defined geofence during a user-defined time period, as long as the vessel has at least one position report with a recorded speed (kts) that falls within a user-defined minimum and maximum speed. For example, if the user does not want vessels that only sat at port the entire study period, then he or she can set the minimum speed greater than 0 kts. The second call returns any available time-stamped position records of these vessels, and other dynamic information such as speed, from the USCG AIS database that fall within the request time period, subject to a user-defined number of records constraint. The server returns records pertaining to any location the vessels traveled during the time period including ones outside the request location.

Field Description Unit Email Email of the requestor, used to send

notifications when the request starts and when the request completes

n/a

Start time Oldest date of AIS records to return Universal Standard Time (UTC) End time Latest date of AIS records to return Universal Standard Time (UTC) Upper left latitude Latitude coordinate of northwestern

most point of the specified location Decimal degrees

Upper left longitude Longitude coordinate of northwestern most point of the specified location

Decimal degrees

Lower right latitude Latitude coordinate of southeastern most point of the specified location

Decimal degrees

Lower right longitude Longitude coordinate of southeastern most point of the specified location

Decimal degrees

Minimum speed Slowest speed vessel must have at least one position report above in ordered to be included in data request

knots

Maximum speed Fastest speed vessel must have at least one position report below in ordered to be included in data request

knots

Number of records per vessel

Maximum number of records returned per vessel for the request. Equals the duration of the study period (min) divided by the user-

record

4

desired time difference between two consecutive records (min/record).

Description Description of what is being requested, such as location and time period

n/a

Another way to query data is through the RIS Proxy Service, which has even more flexible query options. Please see Appendix A for a detailed description.

First Login AISAP is accessed at http://ais-portal.usace.army.mil/.

If this is your first time using AIS, you will need to create an account. Enter your email address and create a password for AISAP.

Creating Projects When you first login after creating your account, you will not have any projects available in the dropdown. Create a project by clicking the green plus symbol.

When you click the green button, a project called ‘New Project’ is created. Change the name so that it is

descriptive of your project and use the save button below to store the changes. You can also add notes to explain the purpose of the project or to provide any other details regarding the project.

The Source is initially empty. Select one or more requests as the source of data for your project.

5

Setting the data source for a project The data source for a project is the returned data of one of more data requests. To set the data source for a

project, click the pencil symbol in the Project Details. The “Find Previous Requests” screen appears. Fill in the desired criteria; note, all fields do not need to be filled in. And/or to filter the requests using a geographical area, click the Draw Area button. Next, click the map to add each vertex of the shape for the area in which to search for requests. Double click to close the area and finish. Click Retrieve Data to display a list of requests that meet the criteria entered and a display of the requests on the map with light gray boxes. Note, darker boxes indicate more than one request was made for that location, such as different requests for different study time periods. Clicking on each box shows a description of the request; for boxes with multiple requests, only one of the request’s descriptions will appear. All the associated requests will populate the requests list. Note the “Num Rec” field is the maximum number of records returned for each vessel and equals the duration of the study period (min) divided by the user-desired time difference between two consecutive records (min/record).

6

To set the data source for the project, check as many requests as desired on the “Requests” list on the left of the screen and then click “Add”.

You will now see the request IDs within the project details on the main screen.

Setting the default data filters for a project Filters provide a way to restrict what vessel position reports associated with the selected data source will be included in the AOI analysis output. By default, without setting any filter options, all reports from the selected data source will be used.

It is recommended that default filters be set for the project prior to creating AOIs. To set the default filters

for a project, click the filter button in the Project Details section. Once the project filters are set, they will be applied to any AOIs that you create afterwards. Please note that changes to the project filters are not applied to existing AOIs, only to future AOIs.

Click the button to view and edit the filters for an individual AOI. The transit time gap, start time and end time are required. The start and end times default to the start and end times for the data source.

7

To enable/disable a filter, click the checkbox to the left of the desired filter.

The Specific Direction option is dependent on drawing an inbound vector on the map. Please see the inbound vector section for more information.

MMSI filter Sometimes you know that the vessels you want to view have a certain MMSI format. AISAP has the ability to create multiple filters for the MMSI. To create an MMSI filter, use the tab at the top of the filter window. You can add multiple expressions so that AISAP will get any records that contain an MMSI that match the

expression you have created. You can create multiple expressions by using the add button .

Sharing a project

By clicking the share button , you can make the current project available to other users in the system. Simply select the desired name from the drop down and click Add. You can remove users by clicking the

8

delete button on the same row as the desired username. In the row field, you can set options for how the user can interact with the project. The three options you can give them are Read Only, Limited Read/Write (allows filters to be edited but the AOI shape is read only), and Full Read/Write.

Creating a duplicate project

When you click the copy button , a new project is created for your user account containing the same description and areas as the project you are currently viewing.

Processing all AOIs in a project If an AOI’s row is yellow, the analysis results are not up-to-date. It may be new or you may have modified the project’s data source or an AOI’s properties such as the shape or filters. To process the data so that the charts and output will match the current project and AOI settings, click the play button to begin processing the data for all AOIs in the project. Please note that processing will occur behind the scenes and takes minutes to hours. The AOIs that are being processed will be disabled, but you may continue working on other projects

and AOIs in AISAP if desired. To check the status of the processing, you may click the refresh button under the Areas of Interest heading.

Deleting a project To delete a project click the delete button . All AOIs and associated information will be removed.

9

Creating Areas of Interest To create an area of interest polygon, you have different options via the buttons in the AOI section. There are

three options available with the import button .

1. You may import a CSV file containing the coordinates for the shape. 2. You may choose to import an ESRI shapefile with its associated DBF file. The file must only contain

one polygon. If more geometry is specified in the file, it cannot be used to create an AOI. 3. You may also manually type the coordinates of the AOI and add and remove points.

Alternatively, click the draw button to draw the AOI. Click to add the vertices to the map and then double click to close and finish adding the area of interest.

If successful, the AOI will be listed below and will be named ‘New AOI’ by default. All the project’s AOIs can be found on the Edit AOIs tab under the Areas of Interest heading.

To zoom to a specific AOI click the zoom button . Change the name by editing the Name field. You must

click the save button to save the new name. By clicking the pencil button , you may adjust the shape of

10

the AOI on the map by moving its vertices. Clicking the copy symbol will allow you to create a copy of

the AOI in another one of your projects. To delete an AOI from your project, just use the delete button on the right.

Adding/Editing AOI Vectors Switching to the Edit Vectors tab allows you to add lines and arrows that are used by AISAP to filter the data for the analysis results.

Inbound Vector

There are three vectors that can be added for an AOI. The Arrow symbol is for specifying the inbound direction for the vessels in the AOI. If inbound is selected on the filter, then vessels generally moving in the direction of the arrow will be selected for analysis. If outbound is selected when the arrow has been set, then vessels moving OPPOSITE of the arrow will be selected for analysis.

To draw an inbound vector, click the arrow button and then click the map and drag in the direction you want the vessels to be moving inbound. Release to complete the vector. When complete, you will see a red arrow indicating the direction of the inbound vector.

Velocity Gate

The velocity gate button adds a line to the map that is meant to be drawn across a channel from bank to opposite bank. The only analysis that uses the velocity gate is the “Vessel Speed Crossing Gate” chart. AISAP displays the speed of vessels that cross it from hourly to monthly fidelities.

11

To draw a velocity gate, click the button and then click the map and drag across a channel. Release to complete the line.

Velocity gate is indicated by the orange line

Channel Center Line

The last vector available is called the Channel Center Line . The only analysis that uses the channel center line is the “Distance from Channel Center” chart. AISAP displays the distance of the vessels from the channel center line.

To draw a channel center line, activate the drawing mode by clicking on the button. Click the map and drag along the channel to draw an initial line. Release to add the line to the map. It will be a green line on the map. Often, the channel center line will require further editing to meander along the center of the channel.

To edit the channel center line, click the button, click and drag to add more vertices. Click and drag any of the border points of the line to stretch or shrink the entire line.

12

Hiding and showing vectors Any of the vectors can be hidden or shown for all AOIs by checking or unchecking the checkbox next to each

of the vector symbols:

Analysis tools in AISAP Creating areas of interest, using the 3 different vectors, and adding filters for AOIs allow you to visualize and obtain useful information regarding the project data. Click the Analysis tab to access these features.

If an AOI’s row is yellow, the analysis results are not up-to-date. It may be new or you may have modified some of the AOI’s properties such as the shape or filters. To process the data so that the charts and output will match the current AOI settings, click the play button to begin processing the data. Please note that processing will occur behind the scenes and may take minutes to hours to complete. The AOIs that are being processed will be disabled. This process can take several minutes to complete. To enable the rows that are no longer beig processed, click the Check Status button. If the rows are still gray then then are still being processed. Wait longer and then retry the Check Status button.

Setting individual AOI filters

To individually adjust the filters for a particular AOI, click the filter button next to the AOI name. This is useful if you want to separate the filters used for each AOI.

13

Charts and graphs showing analysis results When your project has multiple AOIs, you can find the vessel travel times between AOIs by using the Travel Time button above the list of AOIs. This option displays a list of vessels and the travel times between the AOIs in the project. You can export this data to a CSV file.

Several charts are available for each AOI via the charts button . This will reveal a drop down menu giving you these options:

• Summary Statistics – This option include the number of reports, the date range of all the reports, number of unique vessels, the number of transits. Also shows traffic statistics such as Mean and Standard deviation for Vessel Draft, Vessel Length, Vessel Width, Vessel Speed. Five summary charts are also included.

• Filtered Reports – This provides a full list of the vessel position reports included in the selected AOI. • Transit Count – This chart displays the transit count over time for the selected AOI. • Vessel Speed – This chart displays the average vessel speed over time for the selected AOI. • Vessel Speed Crossing Gate – This chart is dependent on setting up the vessel speed crossing gate.

For information on how to set up that vector, please see the vectors section. The chart displays the average vessel speed crossing the line over time.

• Time spent in Area – This provides the length of time each vessel spent in the AOI. If the vessel left and returned to the AOI, the length of time for each visit will be listed.

• Distance from Channel Center Line – This chart is dependent on setting of the distance from center line vector. You will prompted to create one if you have not done so already. For more information on how to do that, please see the vectors section. This chart displays the average distance of the vessels from the channel center line.

Charts can be downloaded to a CSV file and imported into a spreadsheet program for further analysis.

Viewing Vessel transits

Vessel transits can be viewed for vessels in the AOI. By clicking the vessel transit menu and selecting “Select MMSIs”, you can open a pane that will allow you to select individual MMSIs and add their transits to the map. To show all vessel tracks on the map, select the “Show All Transits” option from the vessel transit menu. You can also clear all transits for the selected AOI via the transit menu.

14

You can ctrl+left click to select multiple non-consecutive vessels and shift+left click to select consecutive vessels from the first vessel you click to the last. Clicking Search will display the corresponding vessel transits in the table below the MMSI list.

Clicking the magnifying glass next to one of the transits only shows that transit. You can add all of the transits in the table by clicking Add to Map.

Viewing All transits for an AOI

Heat map Layer

The heat map can be shown for an AOI by clicking on the checkbox next to the heat map symbol . This will render a heat map based on the density of vessel position reports in the AOI. The most intensely packed areas will appear white and the least packed areas will be violet or blue in color.

15

Cluster Layer

When this layer is added by using the cluster layer check box , you will see bubbles with a corresponding number that represents the number of vessel position reports in that location. This is helpful to see with the heat map because you will find out how many vessels actually are being represented by the heat map.

Cluster layer

Cluster layer with heatmap

16

RIS Proxy Service

The RIS proxy service provides real time access to the USCG web services, for small pulls of data, including vessel track lines. Results are outputted in the following formats: XML, JSON, KML, KML track, and KML position. The RIS proxy service is accessed from the Data Requests drop down menu.

Parameters Each of the various services use a subset of parameters to specify the search the user wishes to perform. The proxy service has encapsulated all of these potential parameters into a single composite Parameter object, with fields defined for each value. The RisParams object exposes the following parameters: (Note each service does not require every parameter. By hovering over the different Services format options, the required parameter fields turn red).

Parameter Description MMSI The vessel MMSI number to search on. Accepts wild card character (%)

for certain queries. Name The name of the vessel being searched for. Accepts wild card character

(%) for certain queries.

Call Sign The call sign of the vessel being searched for. Accepts wild card character (%) for certain queries.

IMO Number The IMO Number of the vessel being searched for. Accepts wild card character (%) for certain queries.

Start Time The beginning of the time envelope the user is searching in. Times are assumed by the USCG to be in Zulu time, or GMT.

End Time The end of the time envelope the user is searching in. Times are assumed by the USCG to be in Zulu time, or GMT.

Upper Left Lat The Upper Left Latitude of the bounding box that defines the area the user wishes to search in.

Upper Left Lon The Upper Left Longitude of the bounding box that defines the area the user wishes to search in.

Lower Right Lat The Lower Right Latitude of the bounding box that defines the area the user wishes to search in.

Lower Right Lon The Lower Right Longitude of the bounding box that defines the area the user wishes to search in.

Min Speed (knots) The minimum speed vessels must be traveling for those vessels to register in the search.

Max Speed (knots) The maximum speed vessels can be traveling for those vessels to register in the search.

17

Num Records The maximum number of records per vessel to return with the search.

Real Time Webservices (*note: All queries sent to the USCG are sent in Zulu, or GMT time zone. All data received from the USCG arrives in Zulu, or GMT time zone)

• Vessel Track Line o public String GetVesselTrackLine(RisParams parameters) o Valid Parameters:

mmsi startTime endTime numRecords

o Sample Parameters: MMSI=848507543 StartDateTime=2014-09-12 17:26:14 EndDateTime=2014-10-13 17:26:14 DesiredNumberOfRecords=5000

o Sample Output see file: VesselTrackLine.xml This method returns the vessel track line for the given vessel over the given date

range, at the requested sample rate (numRecords). It’s used to see the individual track a vessel took.

• Vessel Identity o public String GetVesselIdentityXML(RisParams parameters) o public String GetVesselIdentityJSON(RisParams parameters) o Valid Parameters

mmsi (supports wildcards) startTime endTime

o Sample Parameters MMSIWildcard*=338065%25 MMSI*=848507543

• (only supply one of these MMSI parameters, not both) StartDateTime=2014-06-01 00:00:00 EndDateTime=2014-07-22 00:00:00

o Sample Output see file: VesselIdentity.xml This method returns basic information about the vessel or vessels in the query.

Note that this supports wild card searches, and can return multiple results for a given query. The results include the MMSI, IMO Number, Call Sign, Name, and date ranges the given vessel data was valid. This is useful for tracking when things like call sign or vessel name change for a given MMSI number.

18

• Vessel Position o public String GetVesselPositionXML(RisParams parameters) o public String GetVesselPositionJSON(RisParams parameters) o Valid Parameters

Mmsi o Sample Parameters

MMSI=848507543 o Sample Output

see file: VesselPosition.xml This shows the current location (lat/lon) of the given MMSI, and provides basic

vessel information, including Call Sign, Name, Speed, course, the date this position was recorded, and the source type of the data.

• Vessel Position Aggregated List o public String GetVesselPositionAggregatedListXML(RisParams parameters) o public String GetVesselPositionAggregatedListJSON(RisParams parameters) o public String GetVesselPositionAggregatedListKMLTrack(RisParams parameters) o public String GetVesselPositionAggregatedListKMLPosition(RisParams parameters) o Valid Parameters

mmsi startTime endTime numRecords

o Sample Parameters MMSI=848507543 StartDateTime=2014-06-01 00:00:00 EndDateTime=2014-07-22 00:00:00 DesiredNumberOfRecords=500

o Sample Output see file: VesselPositionAggregatedList.xml see file: VesselPositionAggregatedListKMLTrack.xml see file: VesselPositionAggregatedListKMLPoss.xml This method returns the low-resolution (5-minute max resolution) vessel position

data of the given MMSI vessel over the selected date range. The maximum resolution (finest detail you can get) is 5 minute intervals. By using smaller and smaller values of ‘Number of Records’, you can get much longer intervals between aggregate data. Each data point is represented by MMSI, Speed, Heading, Lat, Lon, Course Over Ground, Rate of Turn, Navigation Status, and Receiver information.

• Vessel Position List o public String GetVesselPositionListXML(RisParams parameters) o public String GetVesselPositionListJSON(RisParams parameters) o public String GetVesselPositionListKMLTrack(RisParams parameters) o public String GetVesselPositionListKMLPosition(RisParams parameters) o Valid Parameters

19

mmsi startTime endTime numRecords

o Sample Parameters MMSI=848507543 StartDateTime=2014-06-01 00:00:00 EndDateTime=2014-07-22 00:00:00 DesiredNumberOfRecords=500

o Sample Output see file: VesselPositionList.xml This method returns the high-resolution vessel position data of the given MMSI

vessel over the selected date range. By using larger and larger values of ‘Number of Records’, you can get much shorter intervals between data points than what is available in the aggregate data. Each data point is represented by MMSI, Speed, Heading, Lat, Lon, Course Over Ground, Rate of Turn, Navigation Status, and Receiver information.

• Vessel Position In Area

o public String GetVesselPositionInAreaXML(RisParams parameters) o public String GetVesselPositionInAreaJSON(RisParams parameters) o public String GetVesselPositionInAreaKML(RisParams parameters) o Valid Parameters

upperLeftLon upperLeftLat lowerRightLon lowerRightLat

o Sample Parameters UpperLeftLat=25.83881968468405 UpperLeftLon=-81.94384145895442 LowerRightLat=23.55098381269358 LowerRightLon=-79.22010097682993

o Sample Output see file: VesselPositionInArea.xml This method is used to scan a given box, as described by its upper left corner and

lower right corner, and return all vessels currently inside that box. This method shows real time data, not historical accounts of a region. This method returns several fields about each vessel’s identity, position, and course.

• Vessel Transit o public String GetVesselTransitXML(RisParams parameters) o public String GetVesselTransitJSON(RisParams parameters) o Valid Parameters

upperLeftLon

20

upperLeftLat lowerRightLon lowerRightLat startTime endTime minSpeedKnots maxSpeedKnots

o Sample Parameters UpperLeftLat=25.83881968468405 UpperLeftLon=-81.94384145895442 LowerRightLat=23.55098381269358 LowerRightLon=-79.22010097682993 StartDateTime=2014-04-11 00:00:00 EndDateTime=2014-04-18 00:00:00 MinSpeedKnots=5 MaxSpeedKnots=20

o Sample Output This method returns the list of vessels that were in a region defined by its upper left

corner and lower right corner, over a given data range. This method also allows you to filter out vessels based on speed; for example, if you set a minimum speed of 5 knots, you will not see any vessels that are parked in harbor or waiting for lockage over the requested scan. This method returns several fields about each vessel’s identity, position, and course.

• VoyageHistory o public String GetVoyageHistoryXML(RisParams parameters) o Valid Parameters

Mmsi o Sample Parameters

MMSI=848507543 o Sample Output

see file: VoyageHistory.xml This method call returns a list of all voyage records on file for the given MMSI, as

filed with the coast guard. Each voyage record contains the following information: MMSI, IMO Number, Call Sign, Name, ETA, Destination, Start Time, End Time, and Number of Reports.