1. Help Center
  2. Spire Sense Maritime
  3. Spire Maritime 2.0 - GraphQL API

How the API request rate is limited in Maritime 2.0 GraphQL

How the API request rate is limited in Maritime 2.0 GraphQL

Maritime 2.0 GraphQL allows each token issued to make API requests up to a maximum rate of 60 per minute. Once that limit has been reached subsequent requests still return the requested data but with an artificially enforced slower response time. 

This is necessary to prevent virtual denial of service attacks caused by clients accidentally or deliberately submitting API requests at such a high volume that it causes server over load and prevents other clients from receiving data. 

 

Each graphQL response now contains additional information in the extensions component of the API response that indicates the request quota remaining. This indicates if the API request rate is getting close to exceeding the limit or has indeed already exceeded the limit.

 

Example extensions requestQuota

Here the API call rate limit is not close to being exceeded, 57 further requests in the current minute will be accepted as within the quote for high speed responses.

    "extensions": {
       "requestId": "2626f7bc-d95a-4e7d-bea2-bc51a75344d0",
       "requestQuota": {
           "limit": "60 req/m (burst 60)",
           "remaining": 57
       }
    }

Here the API call rate limit is close to being exceeded, only 4 further requests in the current minute will be accepted as within the quote for high speed responses.

    "extensions": {
        "requestId": "edb80c06-0bad-43ef-b4b5-f6df181bb0c3",
    "requestQuota": {
           "limit": "60 req/m (burst 60)",
           "remaining": 4
       }
  
     


Here the API call rate limit has been exceeded, no further requests in the current minute will be accepted as within the quote for high speed responses. Any further requests made in the current minute will be throttled and returned in a slower time. 

    "extensions": {
       "requestId": "7a4e4067-235d-4e03-9059-052d58892d7a",
       "requestQuota": {
           "limit": "60 req/m (burst 60)",
           "remaining": 0
       }
    }

once the API call rate limit has been exceeded additional information reporting that is returned in an errors object at the head of the API results. A sample of this is below 

{
   "errors": [
       {
           "message": "response to this request was delayed due to rate limiting, maximum allowed quota is 60 req/m (burst 60)",
           "extensions": {
               "code": "TOO_MANY_REQUESTS",
           }
       }
   ],
   "data": {
       "vessels": {
           "totalCount": {
               "relation": "EQUAL",
               "value": 1
           },
           "pageInfo": {
               "hasNextPage": false,
               "endCursor": null
           },
           "nodes": [
               {
                   "id": "b79b57e0-b079-482e-ae02-bf58ee4ebc91",
                   "updateTimestamp": "2022-02-16T14:50:07.860Z",
                   "lastPositionUpdate": {
                       "accuracy": "LOW",
                       "collectionType": "SATELLITE",
                       "course": 158.7,
                       "heading": 155,
                       "latitude": 21.434308333333334,
                       "longitude": 136.93424166666668,
                       "maneuver": "NOT_AVAILABLE",
                       "navigationalStatus": "UNDER_WAY_USING_ENGINE",
                       "rot": 7.5442085,
                       "speed": 15.2,
                       "timestamp": "2022-02-16T13:50:01.000Z",
                       "updateTimestamp": "2022-02-16T14:50:07.860Z"
                   }
               }
           ]
       }
   },
   "extensions": {
       "requestId": "7a4e4067-235d-4e03-9059-052d58892d7a",
       "requestQuota": {
           "limit": "60 req/m (burst 60)",
           "remaining": 0
       }
   }
}