Documentation for Northeast Electronic Monitoring Information System
The NEMIS API is an endpoint for providers of Electronic Monitoring services to submit EM video reviews to the Northeast Fisheries Science Center. There are no endpoints for requesting fisheries data, and the API does not provide public access to any data.
Guidance for EM video reviewers and EM Video Review Protocols from the NOAA Fisheries Greater Atlantic Regional Fisheries Office and Northeast Fisheries Science Center is published here. The instructions below clarify the format and specific requirements of data being submitted through the API that are ambiguous or not well-defined in the API specification. Haul element definitions are detailed in haul element guidance document.
These instructions should not be considered review protocol.
Developers may view the complete OpenAPI v3 specification for this API online or download the file: openapi.json. Changes to the API are logged in the Change log.
The NEMIS API endpoint (url) is:
https://apps-nefsc.fisheries.noaa.gov/NEMIS/index.php/api
All interactions with the EM API require a valid API key (even test submissions), which must be included in the request header as:
X-API-Key: XXXXXX
Keys are granted to qualified software vendors and EM project partners in the participating in the NEFSC Electronic Monitoring observer program. To request an API Key, contact Niki Rossi at Fisheries Sampling Branch, NOAA Fisheries, Northeas Fisheries Science Center: nichole.rossi@noaa.gov
NOAA Fisheries may require an independent, additional review on a subset of trips in select programs (Exempted Fishing Permits (EFPs), experimental programs or projects, new fisheries, etc.). This includes quality assurance and quality control initiatives and providing feedback to the EM service provider on performance. The source of a submission to the EM API is identified by the use of a unique API Key, issued to authorized EM Provider organizations. Agency reviews conducted by FMRD staff using the provider's EM video review software should be submitted to the API in the same way that a provider's (primary) review is done, except by replacing the provider's API Key with one assigned to FMRD.
Access to the API is only provided via a secure connection. Requests to the API through http:// (not secure) will return "405 Method Not Allowed" and a response body:
{
"error": true,
"message": "Unknown method"
}Before accepting EM review data submitted via the API the submitted EM review data are matched against the NEFSC's list of actual trips. The data elements vessel_permit_number and evtr_num must correspond to a trip record that the user is responsible for.
All datetime elements defining each haul must fall between the SAIL_DATE and LAND_DATE on record in the NEMIS database. Absent a match, a "406 Not Acceptable" response is returned with the following:
{
"error": true,
"message": "The request body (EM Review trip data) does not match to a trip."
}Submitted data are validated against a number of rules. Acceptable values for parameters (including the json elements of the /mul_detail and /hrg_detail body) may be found in the OpenAPI Specification for this API. Code descriptions may be found in the API Payload Object Reference.
A comprehensive list of rules and data constraints and their associated API Error Message may be found in the API Constraints page.
Submitting a test submission to the API can be accomplished by appending /test to the url when making a request:
https://apps-nefsc.fisheries.noaa.gov/NEMIS/index.php/api/mul_detail/test
Test submissions are not matched against the NEFSC's trip list. However, the JSON elements vessel_permit_number and evtr_num are still required even though the values will not be compared to NEFSC trip list. Any submission through the API using the /test url will follow the same validation rules as a normal submission but no data will be saved to the NEMIS database. The response to a /test submission will always include the element, "test": true
{
"error": false,
"test": true
}Authentication (using a valid X-API-Key in the header) is required for test submissions to the API.
Datetime values submitted to the API must comply with the ISO 8601 standard for representation of dates and times. Thus, a UTC offset is expected as part of datetime elements in this API. Acceptable formats include:
Note that a date without timezone information is be assumed to represent the local timezone (America/New_York).
Additionally, a date without time will comply with the ISO 8601 standard but will write to the database a time of 00:00:00 (midnight), which is probably not what you intend.
An event that ocurrs over a period of time should be constructed as an "other_event" element with the timestamp denoting the start of the event and an attribute event_duration indicating the length of time that the event occurred. The event_duration value must comply with the ISO 8601 standard for defining Durations. Acceptable formats include:
Note that the event_duration attribute is only allowed on "other_events" elements, and not on "discard_events" nor "hauls" elements. The attribute is generally considered optional (not required) but specific requirements are detailed in the Reviewer Guidance Document. The attribute may be omitted or value set to null, but not zero. event_duration values must be less than 14 days and greater than 0 seconds.
By convention, the event_datetime, event_lat, and event_lon attributes of the event represent the start of the time interval represented by event_duration attribute.
Important note: The API requirements deviate from the ISO 8601 standard in two important ways:
Only one successful submission of an EM review to the API is allowed. If corrections or updates to a previously accepted review are required, contact the NEFSC EM staff and let them know which review needs correcting. If a re-submission is determined to be needed, they may 'unlock' the trip to allow it to be submitted again.
In some instances where an EM trip review is not possible, such as EM system failure or loss of a video data for an entire trip, the API will accept an abbreviated JSON submission that marks the trip as submitted.
In addition to the elements vessel_permit_number and evtr_num, the following elements are required: all_effort_confirmed (must be "N"), and comments (an explanation for the abbreviated review must be noted). Please note the reviewer_id or name of the individual submitting the JSON:
{
"vessel_permit_number": 123456,
"vessel_name": "Fake Vesselname",
"evtr_num": 1234567,
"all_effort_confirmed": "N",
"comments": "Video was corrupted or lost or some other explanation. Submitted by John Smith."
}All changes to the API are recorded on the Change log page.