This page describes the data-consumer facing representational state transfer (REST) architecture providing search and retrieve (SR) functionality for the MISE. By conforming to this interface, the MISE provides data consumers with the ability to find and retrieve the right information at the right time, based on the needs, rights, and authorities of the user and the organizations requesting the information.
| Operation | URI | Description |
|---|---|---|
| Position Search | GET positSearch/?= |
Returns set of all Position instances that match the temporal and geospatial parameters. |
| Position Search (Full) | GET positSearch/?= |
Returns the Position instance for the specified record based on RecordID/EntityID and temporal parameters. If the start and end parameters are not specified, the default time window will be the previous 24 hours. Specifying the full previous 30 day window will return all mda:Position elements for this NIEM-M POS instance. |
| Search | GET search/<iepd>/?= |
Returns set of records of the specified IEPD type based on the query
parameters. A search cannot combine geospatial and term searches. If both are specified, the MISE will use the geospatial parameters only. If the start and end parameters are not specified, the default time window will be the previous 24 hours. |
This interface provides a paginated search interface, which breaks large query results sets into "pages" based on time windows, which will be explained in the next sections.
All interactions with the SR interface are secured as described by the MISE Interface Security Specification. For search and retrieve operations, both the Trusted System Authentication and the User Attribute Conveyance portions of the interface security specification apply. All records available on the MISE are formatted using NIEM-Maritime, as described in the National MDA Architecture Information Exchange Package Documents (IEPD).
All interactions with the MISE are done over Secure Socket Layer/Transport Layer Security (SSL/TLS) connections. SSL/TLS are enforced to protect information in transit and session cookies. Each client querying against the search interfaces is authenticated by the MISE and is provided with a limited-duration session cookie, which must be supplied in the header of following requests. The method for authentication is discussed the MISE Interface Security Specification.
The MISE search interface uses the following HTTP headers for specific purposes. All other HTTP headers should be interpreted according to the HTTP 1.1 standard.
- Accept: By default, if no Accept is specified, the summary feed will be returned in the Atom format as specified above. However, the following Accept headers may be supplied, resulting in translated feeds:
- application/kml – returns the <mise-recordset> feed translated into a KML overlay.
The MISE provides a position search service that allows the consumer to search for updated positions on the MISE based on temporal and geospatial parameters. This provides back a set of all Position instances that match the search parameters.
| Position Set Search Service | ||
|---|---|---|
| URI | BaseURI/positSearch/?= | Example: https://services.mda.gov/positSearch/? start=2013-08-28T22:20:56&end=2013-08-28T22:22:56 &ulat=39.636756&ulng=-77.148293 &llng=-75.793459&llat=38.528532 |
| Method | GET | |
| Request Headers | Authorization | As described in the MISE Interface Security Specification. |
| Request Content Type | Empty | |
| Status Codes | 200 (Success) | Returns the results described below. |
| 400 (Bad Request) | Request was not formatted correctly. | |
| 401 (Unauthorized) | No Authorization header. | |
| 403 (Forbidden) | Invalid authentication information. | |
| 5xx (Error) | Error in position search. The body content will provide error details. | |
| Response Headers | Empty | |
| Response Content Type | <mise-recordset> containing results | See example below. |
The position search service requires all six parameters to be specified:
| Position Set Search Parameters | ||
|---|---|---|
| start | ISO8601 DateTime | start of the query time window in GMT |
| end | ISO8601 DateTime | end of the query time window in GMT |
| ulat | WGS84 | upper left latitude of a bounding box |
| ulng | WGS84 | upper left longitude of a bounding box |
| llat | WGS84 | lower right latitude of a bounding box |
| llng | WGS84 | lower right longitude of a bounding box |
The position set search returns an <mise-recordset> element containing the results of the search. For full details on the <mise-recordset> and pagination, see the description in the General Batch Search Interface section. The <mise-recordset> contains the Position instances matching the query parameters. Each instance contains the Vessel information and one or more associated <mda:position> elements, where the position datetime of each <mda:position> element is within the time window specified by the start and end parameters, and where the position falls within the geospatial box defined by the other four parameters. The <mda:position> elements are time-ordered from newest to oldest. The full Position instance for any result can be easily queried using the retrieval interface described below.
Given the entity ID and record ID of a NIEM-M POS record published to the MISE, which has presumably been updated with further positions, the track retrieval interface provides the ability to query for some or all positions for a specific record.
| Full Position Instance Retrieve Service | ||
|---|---|---|
| URI | BaseURI/positSearch/?= | Example: https://services.mda.gov/positSearch/? start=2013-07-28T22:20:56&end=2013-08-28T22:22:56 &recordid=12345678&entityid=agencyone.gov |
| Method | GET | |
| Request Headers | Authorization | As described in the MISE Interface Security Specification. |
| Request Content Type | Empty | |
| Status Codes | 200 (Success) | Returns the NIEM-M POS instance corresponding to the query. |
| 400 (Bad Request) | Request was not formatted correctly. | |
| 401 (Unauthorized) | No Authorization header. | |
| 403 (Forbidden) | Invalid authentication information. | |
| 5xx (Error) | Error in position search. The body content will provide error details. | |
| Response Headers | Empty | |
| Response Content Type | Single NIEM-M POS instance | See example below. |
| Full Position Instance Retrieve Parameters | ||
|---|---|---|
| start | ISO8601 DateTime | start of the query time window in GMT |
| end | ISO8601 DateTime | end of the query time window in GMT |
| recordID | String | ID of the POS record, content of the RecordIDURI element |
| entityID | String | Entity ID of the publisher of this record |
The full position instance retrieve service requires only that the record ID and entity ID parameters be specified. If the start and end parameters are not specified, the MISE will query over the last 24 hours. The number of <mda:position> elements provided back in the response is based on the time range specified in the query. Specifying the full previous 30 day window will return all <mda:position> elements for this NIEM-M POS instance. If the start and end parameters are not specified, the default time window will be the previous 24 hours.
The returned XML will be a NIEM-M POS instance with one or more <mda:position> elements that fall within the specified time range. See the example file here. The <mda:position> elements will be ordered from newest to oldest in time.
For the purposes of this document, the MISE is assumed to be accessible at the global uniform resource identifier (URI) https://services.mda.gov/services/MDAService, provided as an example base URL. SR provides a series of URL endpoints that provide global query functionality and focus-area-specific (or IEPD-specific) queries. The query URLs have the following form: https://services.mda.gov/search/iepdname/?=
The iepdname takes the form of one of the message types provided by the MISE. Currently, these are:
- noa (Notice of Arrival)
- ian (Indicator and Notification)
- vinfo (Vessel Information)
- loa (Levels of Awareness)
- pos (Position) - this query only returns the base published Position instance, not the full Position instance with all updated positions. For that, use the previously described Position Retrieve search.
Each URI in association with an IEPD name queries a single record type. For example, https://services.mda.gov/search/noa?= provides the notice-of-arrival specific query endpoint. Using this scheme, further endpoints can be added for specific queries as new record types are defined for new focus areas.
| Batch Search Service | ||
|---|---|---|
| URI | BaseURI/IEPDName/?= | Example: https://services.mda.gov/search/noa/?start=2013-08-27T22:20:56&end=2013-08-28T22:22:56 |
| Method | GET | |
| Request Headers | Authorization | As described in the MISE Interface Security Specification. |
| Request Content Type | Empty | |
| Status Codes | 200 (Success) | Returns the body content. |
| 400 (Bad Request) | Request was not formatted correctly. | |
| 401 (Unauthorized) | No Authorization header. | |
| 403 (Forbidden) | Invalid authentication information. | |
| 5xx (Error) | Error in position search. The body content will provide error details. | |
| Response Headers | Empty | |
| Response Content Type | <mise-recordset> containing results | See example below. |
The query URL for each IEPD type can be combined with a set of query parameters to narrow the results returned.
| Parameter Name | Value Type | Comment |
|---|---|---|
| start | ISO8601 DateTime | GMT |
| end | ISO8601 DateTime | GMT |
| ulat | WGS84 | upper left latitude of a bounding box |
| ulng | WGS84 | upper left longitude of a bounding box |
| llat | WGS84 | lower right latitude of a bounding box |
| llng | WGS84 | lower right longitude of a bounding box |
| VesselName | String | |
| VesselSCONUMText | String | |
| VesselMMSIText | String | |
| VesselIMONumberText | String | |
| VesselNationalFlag | String | |
| VesselClassText | String | |
| VesselCallSignText | String | |
| VesselHullNumberText | String | |
| VesselOwnerName | String | |
| VesselCategoryText | String | |
| InterestCategoryCode | String | |
| InterestLevel | String | |
| PortNameText | String | |
| InterestType | String | |
| InterestCategory | String | |
| InterestLevel | String | |
| InterestStart | ISO8601 DateTime | GMT |
| InterestEnd | ISO8601 DateTime | GMT |
| ArrivalPort | String | |
| ExpectedArrivalTime | ISO8601 DateTime | GMT |
| eid | String | The eid parameter allows a consumer to specify a specific data provider. This field must contain the entity ID of a provider system from the Trust Fabric document. This is only used in addition to other parameters |
| NoticeType | String | |
| NoticeTransactionType | String | |
| CDCCargoDeclared | Boolean | T or F |
| ActivityName | String | |
| ActivityStart | ISO8601 DateTime | GMT |
| ActivityEnd | ISO8601 DateTime | GMT |
| LevelOfAwarenessCode | Integer | This parameter is applied to queries specifically for the Levels of Awareness IEPD type. This specifies the LOA level |
A search cannot combine geospatial and term searches. If both are specified, the MISE will use the geospatial parameters only. The start and end parameters are implicitly required. If not specified, the MISE defaults to the last 24 hours.
For specific events and situations, the MISE provides an additional set of query parameters that can be used to query for messages within a specific scope. When applied by an information publisher, the scope parameters modify the entitlements for a record for the duration of the scope. This, in combination with the entitlements specified as part of the authentication process, may allow a consumer access to additional information.
| Parameter Name | Value Type | Comment |
|---|---|---|
| Scope | String |
Table 7 – Scope Search Arguments
For example, consider a Search query for
all notice of arrival messages inbound to the Port of Miami during
Hurricane Katrina:
Valid scope values can be found on the National MDA Architecture website.
As an example, consider a query for all notice of arrival instances in a 24-hour period: https://services.mda.gov/search/noa/?start=2013-08-27T22:20:56&end=2013-08-28T22:22:56a>. The results are broken up in to sets or “paginated” based on time and the number of records in the result set. Each page of records includes a link for the next set of records, moving from the newest to the oldest, if there is more than one page of results.
The interface returns an <mise-recordset> element, containing up to 250 results in the following form. Both the Position Search and General Batch Search interfaces use this format.
<?xml version="1.0" encoding="UTF-8"?> <mise-recordset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../../position-3.2.iepd/XMLschemas/exchange/3.2/mise-recordset.xsd" pageElements="250" query="https://services.mda.gov/search/noa/?start=2013-08-27T22:20:56&end=2013-08-28T22:22:56" nextQuery="https://services.mda.gov/search/noa/?start=2013-08-27T22:20:56&nextTime=2013-08-27T22:20:00:001"> <posex:Message> ...snip...</posex:Message> <posex:Message> ...snip...</posex:Message> [... next 248 records] </mise-recordset>
Listing 1 – Example Search Result Content
This search would normally return a very large number of results. Rather than overwhelm the consuming system and the network with a single very large XML result set, the results are “paginated” into smaller sets of records, bounded by time. This pagination is based on the number of records returned, to prevent overwhelming the network and the consuming system. Figure 1 shows how this works:
Figure 1– Pagination
The pages are not fixed in time. Rather, they are fixed based on the record limit. That is, if there are N records in 30 seconds, then that page is 30 seconds long. The pages move in time from the end datetime of the query to the start datetime of the query, from newest to oldest. Allowing each page to have a dynamic time period allows the MISE to split clustered results into fixed size result sets.
The returned XML carries a number of important attributes in the element that wraps the results.
| Attribute | Description |
|---|---|
| query | Provides the URL of the original query to the system. |
| nextQuery | Provides the next page of results. This is the link pointing to the next page of records. The next page starts at nextTime 2013-08-27T22:20:00.001 and will return the next set of records, up to the record limit. If there are more records, another nextQuery attribute will point to the next result page. This will continue until the nextQuery attribute does not appear in the result, which indicates there are no more records. The start argument is carried through each page so the MISE knows when to stop returning pages. All queries to the batch search/retrieve interface should have the start and end parameters specified. If not specified, then the query defaults to the last 24 hours. For highly clustered results, where many results occur in a short time period, the nextTime argument may be specified down to the millisecond, so the receiving system should handle the .NNN millisecond format for the ISO8601 DateTime. nextQuery will not be included in the last page of the results. |
| pageElements | Provides the number of records in this result set. |
| pageStart | The beginning of the time range of the records in this recordset. |
| pageEnd | The end of the time range of the records in this recordset. |
Table 8 – <mise-recordset> Attributes
Finally, if other query parameters, such as geospatial or vessel identifiers are specified, they are carried through on the nextQuery links. For example, if the geospatial query is:
https://services.mda.gov/search/noa/?content=full&start=2013-08-27T22:20:56&end=2013-08-28T22:22:56&ulat=39.636756&ulng=-77.148293&llng=-75.793459&llat=38.528532
The next page link would look like this:
If the search were for a specific Vessel Identifier:
https://services.mda.gov/search/noa?content=full&start=2013-08-27T22:20:56&end=2013-08-28T22:22:5&VesselMMSIText=123456789
The nextQuery link would be:
https://services.mda.gov/search/noa?content=full&start=2013-08-27T22:20:56&nextTime=2013-08-28T20:22:56&VesselMMSIText=123456789
The consuming system can iteratively follow the next page links until all records matching the query have been retrieved, when they receive a page with no nextQuery attribute.