Don't see what you need? Submit a request

S&A API introduction

Jaivin Anzalota -

This describes how a client should request resources, and how the server will respond to those requests for the Routehappy Scores & Amenities API v3.

To obtain an API key, sign up for access or sign in to your account dashboard using the credentials established when your account was created.

Headers

Name Required Description
Accept Yes Specifies the media type and version. Must be application/vnd.api.v3+json for this version of the API.
Auth Yes Your API key.
Accept-Language No Used for translation of the display_text properties. The use of this header is documented under RFC 3282.
Accept-Encoding No All API requests support gzip and deflate HTTP compression. To receive compressed response bodies, send the gzip, deflate. The type of compression used will be in the Content-Encoding response header.

Document Structure

This section describes the structure of an API document. API documents are defined in JavaScript Object Notation (JSON) [RFC 7159].

Top Level

Property Type Description
data array The document’s “primary data.” A collection of resources targeted by a request.
linked object Resource objects that are related to the primary data and/or each other (“included resources”).

Resource Objects

A resource objects contains an id property and any number of other attributes, depending on the resource type.

Here’s an example seat resource:

{
  "id": 2,
  "display_text": "Above average legroom (32\")",
  "quality": "better",
  "legroom": "more",
  "pitch": "32",
  "width": "standard",
  "flatness": "not flat",
  "type": "above average legroom",
  "updated_at": "2016-07-01T06:09:52Z"
}

In addition, a resource may also contain a links property, an object containing links related to the resource.

Here’s an example segment resource, containing a seat link:

{
  "id": "PHX-MCO-AA-436-20161215-ECON",
  "links": {
    "seat": 2
  }
}

Fetching Data

Data can be fetched by sending a GET request to an endpoint.

For example, the following request fetches a collection of segments:

curl \
  -H "Auth: YOUR_API_KEY" \
  -H "Accept: application/vnd.api.v3+json" \
  -G \
  -d ids=PHX-MCO-AA-436-20161215-ECON \
  YOUR_HOST/segments

Important
* Due to URL length limitations, ids parameters can be sent in the request body. If you do so, use the POST method.

An endpoint MAY return resources related to the primary data by default. An endpoint MAY also support an include request parameter to allow the client to customize which related resources should be returned.

The value of the include parameter MUST be a comma-separated list of relationship paths. A relationship path is a dot-separated list of relationship names.

For example, a relationship path could be segments.seat, where segments is a relationship listed under a legs resource object, and seat is a relationship listed under a segments resource object.

Here’s an example request and response:

curl \
  -H "Auth: YOUR_API_KEY" \
  -H "Accept: application/vnd.api.v3+json" \
  -G \
  -d ids=PHX-MCO-AA-436-20161215-ECON \
  -d include=segments.seat \
  YOUR_HOST/legs
{
  "data": [
    {
      "id": "PHX-MCO-AA-436-20161215-ECON",
      "links": {
        "segments": [
          "PHX-MCO-AA-436-20161215-ECON"
        ]
      }
    }
  ],
  "linked": {
    "segments": [
      {
        "id": "PHX-MCO-AA-436-20161215-ECON",
        "links": {
          "seat": 2
        }
      }
    ],
    "seats": [
      {
        "id": 2,
        "display_text": "Above average legroom (32\")",
        "quality": "better",
        "legroom": "more",
        "pitch": "32",
        "width": "standard",
        "flatness": "not flat",
        "type": "above average legroom",
        "updated_at": "2016-07-01T06:09:52Z"
      }
    ]
  }
}

Response Status Codes

Code Description
200 Successful request.
404 The requested endpoint does not exist.
401 Authentication failed. Check the Auth header.
415 Invalid Accept header.
400 Generic client error.
503 The server is overloaded or down for maintenance. This is a temporary condition which will be alleviated after some delay.
500 The server encountered an unexpected condition which prevented it from fulfilling the request. This is a generic status code, given when no other specific status code is suitable.
Have more questions? Submit a request