Introduction

The Traxo API can be used to access travel information on behalf of Traxo members.

Versioning

Current API Version: v2 (November 1, 2013)

All Traxo API endpoints include a version identifier as part of the url.

Examples:

https://api.traxo.com/v2/me
https://api.traxo.com/v2/trips/upcoming

Within a given version, clients can be assured that no backwards incompatible changes will be made under normal circumstances. Additional response parameters may be present at any time (see New / Experimental / Unsupported Fields section below).

Data Types and Values

Content Type

The Traxo API serves responses with the "application/json" Content-Type.

JSON Data

JSON (as defined by ECMA-404 The JSON Data Interchange Standard) is supported by every modern programming language and application framework.

API responses may take the form of a JSON object (a collection of name/value pairs) or a JSON array (an ordered list of values) as defined by the standard.

A JSON value can be a string in double quotes, or a number, or true or false or null, or an object or an array.

API responses may contain parameters with null or empty string values. These values indicate an absence of data and should be handled as such by the consumer of the API response.

Identifiers

Traxo resources are typically identified using 64-bit integers delivered as string values.

While not guaranteed, Traxo resource IDs are typically unique globally for a given resource type.

Traxo resource IDs are generally time ordered and not sequential.

Examples: "534619485683827958" "534619485683828212"

See the Traxo API definitions for details and examples specific to each resource.

Dates and Times

All dates and datetimes comply with the ISO8601 standard.

We remove the timezone offset specification for dates and datetimes that are assumed to be local. Many of our travel data suppliers report datetimes as local.

Examples:

2008-10-20T11:45:25+0000 - A datetime with zero timezone offset (i.e. this is UTC)
2008-10-20T11:45:25 - A local datetime
2008-10-20 - A local date (no time is specified), typical for hotel segments

When available, we may include a timezone identifier (string) field that can be interpreted by most modern programming languages to determine daylight savings time and normal offsets from UTC.

Examples:

America/Chicago
America/Costa_Rica

Error Responses

When errors are encountered with a given request, the response will include an appropriate HTTP response code, an error code string, and an error description in English. The documentation for each method will show error codes that could be expected.

Example HTTP Response header:

401 Authorization Required

Response body:

{
    "error":"invalid_request",
    "error_description":"The access token was not found."
}

Common Error Responses:

  • https_required: HTTPS is Required. See API documentation
  • http_post_required: HTTP POST is required
  • not_supported: Endpoint not supported
  • service_error: Please contact customer service
  • not_found: Item not found
  • invalid_request: Invalid parameters
  • access_denied: You do not have access to the item
  • validation_error: Validtion failed

Common OAuth-related Responses:

  • invalid_client: Missing client_id
  • client_rate_limit: This client_id is invalid or over limit

Validation Error Responses

When submitting data to the API, fields that do not pass internal validation checks will trigger a `validation_error` response. This response will usually contain a fields object with a key for each input parameter that failed validation and one or more textual messages for each key.

{
    "error":"validation_error",
    "error_description":"Validation failed",
    "fields": {
        "origin": [
            "Invalid origin airport"
        ]
    }
}

HTTP Response Codes

We try to send an appropriate HTTP response code so you can avoid the overhead of parsing the response if you don’t need to.

Examples:

  • 200 OK: Success (upon a successful GET, POST, PUT, or DELETE request)
  • 201 Created: Created (upon a successful POST request creating a new record)
  • 202 Accepted: The request has been accepted for processing
  • 304 Not Modified: There was no new data to return
  • 400 Bad Request: Resource Invalid (improperly formatted request, an error message will be included)
  • 401 Unauthorized: Unauthorized (incorrect or missing Member credentials or API User authentication)
  • 403 Forbidden: The request is understood, but it has been refused
  • 404 Not Found: Resource Not Found
  • 429 Too Many Requests: You are being rate limited
  • 500 Internal Server Error: Application Error

New / Experimental / Unsupported Fields

New fields may be added to API responses within a fielded version as business and market needs dictate. Developers should ensure that their integrations graceful handle these additional fields.

Any field name with a leading underscore should be considered experimental and unsupported and may be removed at any time.

These fields are used to test new features and concepts or to support debugging and troubleshooting efforts.

If you see one of these that you really want or need, send us a message: api-support@traxo.com