Using the API

This document goes into more detail about the various operations you can perform with the API.

Pagination

When making an API request, you usually don't receive all of the results of that request in a single response. This is because some responses could contain thousands of objects so most responses are paginated by default.

Cursor-based Pagination

Cursor-based pagination is the most efficient method of paging and should always be used when possible. A cursor refers to a random string of characters which marks a specific item in a list of data. The cursor will always point to the item, however it will be invalidated if the item is deleted or removed. Therefore, your app shouldn't store cursors or assume that they will be valid in the future.

When reading an edge that supports cursor pagination, you see the the following JSON responses:

Flight Info API:

{ 
"data": [ ... Endpoint data is here],
"paging": {
"limit": 1,
"totalCount": 23,
"totalPages": 23,
"next": "https://api.oag.com/flight-instances?departuredate=2021-10-28&limit=1&version=Preview&after=i58A%2BI%2BUrMG9luyc9txY%2BUEUVgDABhxHOJgO6sMgOpDcAhiwwSrWdT5wPWxme8Ag46kC9r%2Bx7Rmrrke5MNY3D1bIjLwAK6HA45MXCC8Ft5UGr%2BJbLzibZSK%2FzU2b3y3CtxmYL2OtPo21WWNZVTIDtWEGIotUP8LKSBVtrF6r1RvI5SWsClk4j%2FaLGWAf2K12D1nYjZ6AgSTBD%2FcM"
}
}

Schedules and Flight Info Changes APIs:

{ 
"data": [ ... Endpoint data is here],
"paging": {
"limit": 1,
"totalCount": 23,
"totalPages": 23,
"previous": "https://api.oag.com/flights?flightnumber=1999&limit=1&cursor=119fa354673727b9971fe0ab2865d23415288d511af9e2d7e6493f817a10124e",
"next": "https://api.oag.com/flights?flightnumber=1999&limit=1&cursor=27acc7c8e30ebc22a573ac2706aea926fe1e9c33f6c7bc255df118134b7760c6"
}
}

A cursor-paginated edge supports the following parameters:

  • limit : This is the maximum number of objects that may be returned. A query may return fewer than the value of limit due to filtering.

  • totalCount : This is the total amount of records returned by the query.

  • totalPages : This is the total amount of pages returned by the query.

  • previous*: The API endpoint that will return the previous page of data.

  • next : The API endpoint that will return the next page of data. If not included, this is the last page of data. Stop paging when the next link no longer appears.

*Only returned for Schedules API.

Health Check API

The Health APIs are public endpoints that give information on each service's health.

Request

The following are examples of requests to Health Check API:

GET /flights/health
GET /schedules/health

Response

Depending on the service health status the following responses can be returned:

  • HTTP Status 200 OK

  • HTTP Status 503 Service Unavailable

Sample 200 OK response (Flight Info API):

{
"flightInfo": "healthy"
}

Sample 503 Service Unavailable response (Schedules API):

{
"schedules": "unhealthy"
}

Knowledge Base

Have a question? The OAG knowledge base is full of frequently asked questions, how-to guides, and product documentation, designed to make it quick and easy for you to access information, regarding integrating and using the OAG APIs. You can access our Knowledge Base here.