Getting StartedUsing the API

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 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.

Flight Info API

json

{
  "data": [ ... data ],
  "paging": {
    "limit": 1,
    "totalCount": 23,
    "totalPages": 23,
    "next": "https://api.oag.com/flight-instances?DepartureDate=2022-05-28&Limit=1&version=1.0&After=202205280705-..."
  }
}

Schedules API

json

{
  "data": [ ... data ],
  "paging": {
    "limit": 1,
    "totalCount": 23,
    "totalPages": 23,
    "previous": "https://api.oag.com/flights?departuredate=2023-03-09&limit=1&cursor=0000082f...",
    "next": "https://api.oag.com/flights?departuredate=2023-03-09&limit=1&cursor=00010cd3..."
  }
}

limit

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

totalCount

The total amount of records returned by the query.

totalPages

The total amount of pages returned by the query.

previous *

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

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.

* previous is only returned for the Schedules API.

Health Check API

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

Request

bash

GET /flights/health
GET /schedules/health
GET /master-data/health

Response

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

200 OK503 Service Unavailable

Sample 200 OK (Flight Info API)

json

{
  "flightInfo": "healthy"
}

Sample 503 Service Unavailable (Schedules API)

json

{
  "schedules": "unhealthy"
}

Cross-Origin Resource Sharing (CORS)

Server-side Integration Required

Cross-Origin Resource Sharing (CORS) is not allowed for OAG APIs. To integrate the API, use a server-side approach — enabling CORS on the front-end would expose your subscription key to the public and allow misuse.

API Version Lifecycle

After the launch of a subsequent version, a version will be retired approximately one year later. A version will be flagged as deprecated once the next version is released.

A deprecated API version will start returning two new response headers indicating the sunset date:

bash

deprecation: true
sunset: 2024-05-01

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 find information about integrating and using the OAG APIs. Access the Knowledge Base