Multimodal Travel API


Faretrotter Travel API is a multimodal travel search API designed to return every transportation option between two cities. The API opens access to more than 12 million transportation routes, connecting more than 30,000 cities around the globe. Our multimodal API returns data for flights, trains, buses, and much more. Implement the API as a way to boost your content marketing, support your app development, or fill in the gaps where needed.

For ease of use, we have built the travel API as a simple to use, RESTful service. The API accepts and serves JSON as requests and responses, all of which is well-documented with complete examples below.

If you are interested in using our API for a study, or require other formats, please contact us here.

Getting Started

To gain access to the API, please register below. Once you do this, we will have to validate your account before you can start making requests.

To make the API as explorable as possible, each account is provided with development and production keys. There is no "switch" for changing between modes, simply use the appropriate key and environment to perform a request to production or development.

We use GitHub as a way to communicate our releases, accept enhancement requests, and for reporting bugs. If you'd like to see something added to the API, please tell use about it here.

Authentication

Authenticate your account by including your secret key in API requests. Manage your API keys in the Dashboard. Your API keys are tied to your account, so be sure to keep them hush hush! Do not share your private API keys in publicly accessible areas such as GitHub, client-side code, and so forth. It is best practice to use your private key with server-side requests.

The development environment is the same for every account. Upon getting ready to launch your application, the production environment assigned to your account will be located on your account details page.

Versioning

When we make backwards-incompatible changes to the API, we release new, dated versions. The current version is v2.0. Read our API upgrades guide to see our API changelog and to learn more about backwards compatibility. All requests will use your account API settings, unless you override the API version. The changelog lists every available version. Note that events generated by API requests will always be structured according to your account API version.

We make regular updates to our API, denoted in our format: x.y where x is the major version, y is a subversion. The current version is 2.0. For major and minor updates, we include release notes.

Errors

Faretrotter makes use of HTTP response codes to indicate the success or failure and general statuses of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided, while 5xx indicate server-side errors.

200
OK
Everything worked as expected.
400
Bad Request
Parameters did not match the endpoint requirements. Check that all required fields are present and spelt correctly.
401
Unauthorized
Authentication Failed
402
Request Failed
All parameters are correct but the request failed.
402
IP Conflict
Request IP does not match IP address registered with key.
404
Not Found
The endpoint doesn't exist.
429
Too Many Requests
Too many requests hit the API too quickly.
501, 502
Server Errors
Something has gone awry.

Usage

Rate limiting of API usage is on a per-user basis — or more accurately described, per user access token. For development, the rate limit is 500 requests per hour and 3000 per day. The standard production rate limit is 1000 requests per hour and 10000 per day. Anything above this, get in-touch with us and we will accommodate heavier loads.

For educational or hackathon applications, we may be able to increase usage rates and create users for special events. Please notify us at least one week prior to initial use.

Account

To setup an account, please go here. We review each user individually, so automatic API access is not typically granted. You’ll need to provide some information to help us identify how you’ll be using our resources.

Once granted access, you can access your account to setup up private and public keys, which you can use to make calls to the API. For public keys, you will also use your account to establish trusted hostnames for your requests. For private keys, you will need to authorize your source IP address. We do this sort of authentication solely for an additional level of authenticity.

Places

The Places endpoint supports both free form text and reverse geolocation place search. See the table below for required fields.

Free Form Text Search

Request

input_text
Required
Free form text search
String

Response

requestRequest fields
Array
statusStatus message
Array
placesList of places
Array

Reverse Geolocation

Request

lat
Required
Latitude
Decimal
lng
Required
Longitude
Decimal

Response

requestRequest fields
Array
statusStatus message
Array
placesList of places
Array

Places

Response

idPlace ID
String
nameName
String
name_longFull Name of Place
String
citycity
String
regionRegion / State
String
countryCountry
String
typeType
Decimal
slugSlug
String
latLatitude
Decimal
lngLongitude
Decimal
geoname_idGeoname ID
String

Routes

The Routes endpoint is used to return modes of transportation between two places. Required requests parameters are geo coordinates or fully qualified place names. Additionally, there are several optional fields such as radius and various modes.

Response

requestRequest fields
Array
statusStatus message
Array
routesList of routes
Array
responseResponse fields, including URL
Array
placesList of places
Array
operatorsList of operators
Array

Route Options

Response

origin_place_idOrigin ID
String
destination_place_idDestination ID
String
modeMode
String
fareFare Amount
Decimal
durationTotal duration in seconds
Decimal
operator_idOperator ID
String
co2CO2 Emissions Estimate (in kg)
Decimal
segmentsSegments (for trains or public transport)
Array

Operators

Response

idOperator ID
String
nameName of operator
String
logo_imgOperator logo
String
modeMode
String
codeOperator Code (if applicabe - i.e. IATA code)
String
attributesList of attributes about operator
Decimal

Supported Modes

List of Modes

flightFlight
busIntercity Bus
dog_sledDog Sled
ferryFerry
funicularFunicular
private_transferPrivate Transfer (from airport)
public_transitPublic Transport
shuttleShuttle
trainTrain
trolleybusTrolleybus
walkWalking connections
driveDrive/Carpool
rideshareRideshare (i.e. Lyft or Uber)
Please sign up before accessing request information.

Authentication Key Request Example

https://api-dev.faretrotter.com/v2.0/SECRET_KEY/:endpoint?:request-parameters

Environment Request Example

https://ENVIRONMENT.faretrotter.com/v2.0/:secret-key/:endpoint?:request-parameters

API Version Example

https://api-dev.faretrotter.com/VERSION/:secret-key/:endpoint?:request-parameters

Standard Error Format

{
    "error": {
        "code": "200",
        "message": "OK"
    }
}

Free form text request

https://api-dev.faretrotter.com/v2.0/:secret-key/places?input_text=paris

Free form text response

{
    "request": {
        "environment": "api-dev",
        "version": "2.0",
        "endpoint": "places",
        "fields": {
            "input_text": "paris"
        }
    },
    "status": {
        "code": "200",
        "message": "OK"
    },
    "places": [
        {
            "id": "1",
            "name": "Paris",
            "name_long": "Paris, France",
            "city": "Paris",
            "region": "\u00cele-de-France",
            "country": "FR",
            "type": "city",
            "lat": 48.85341,
            "lng": 2.3488,
            "geoname_id": "2988507"
        },
        {
            "id": "2",
            "name": "Paris",
            "name_long": "Paris, Texas, United States",
            "city": "Paris",
            "region": "Texas",
            "country": "US",
            "type": "city",
            "lat": 33.66094,
            "lng": -95.55551,
            "geoname_id": "4717560"
        }
    ]
}

Reverse geolocation request

https://api-dev.faretrotter.com/v2.0/:secret-key/places?lat=33.640728&lng=-84.4277&radius=10

Reverse geolocation response

{
    "request": {
        "environment": "api-dev",
        "version": "2.0",
        "endpoint": "places",
        "fields": {
            "lat": 33.640728,
            "lng": -84.4277,
            "radius": 10
        }
    },
    "status": {
        "code": "200",
        "message": "OK"
    },
    "places": [
        {
            "id": "1",
            "name": "ATL",
            "name_long": "ATL Hartsfield Jackson Atlanta Intl",
            "city": "Atlanta",
            "region": "GA",
            "country": "US",
            "lat": "33.640753",
            "lng": "-84.443174",
            "geoname_id": "4199556"
        },
        {
            "id": "2",
            "name": "Atlanta",
            "name_long": "Atlanta, GA, US",
            "city": "Atlanta",
            "region": "GA",
            "country": "US",
            "lat": "33.749",
            "lng": "-84.38798",
            "geoname_id": "4180439"
        },
        {
            "id": "3",
            "name": "East Point",
            "name_long": "East Point, GA, US",
            "city": "East Point",
            "region": "GA",
            "country": "US",
            "lat": "33.67955",
            "lng": "-84.43937",
            "geoname_id": "4192674"
        },
        {
            "id": "4",
            "name": "Little Five Points",
            "name_long": "Little Five Points, Decatur, Georgia, United States",
            "city": "Decatur",
            "region": "GA",
            "country": "US",
            "lat": "33.76511",
            "lng": "-84.34909",
            "geoname_id": "4206099"
        }
    ]
}

Place entity

{
    "id": "1",
    "name": "ATL",
    "name_long": "ATL Hartsfield Jackson Atlanta Intl",
    "city": "Atlanta",
    "region": "GA",
    "country": "US",
    "lat": "33.640753",
    "lng": "-84.443174",
    "geoname_id": "4199556"
}

Routes request

https://api-dev.faretrotter.com/v2.0/:secret-key/routes?origin_lat=34.0156082&origin_lng=-118.68505&destination_lat=37.7576793&destination_lng=-122.5076401&curr=USD&modes=flight,bus,train,drive

Routes response

{
    "request": {
        "environment": "api-dev",
        "version": "2.0",
        "endpoint": "routes",
        "fields": {
            "origin_lat": 34.0156082,
            "origin_lng": -118.68505,
            "destination_lat": 37.7576793,
            "destination_lng": -122.5076401,
            "curr": "USD"
        }
    },
    "status": {
        "code": "200",
        "message": "OK"
    },
    "routes": [
        {
            "origin_id": "1",
            "destination_id": "6",
            "mode": "bus",
            "fare": 24,
            "duration": 27900,
            "operator_id": "1",
            "co2": "20.88",
            "segments": []
        },
        {
            "origin_id": "2",
            "destination_id": "7",
            "mode": "bus",
            "fare": "32",
            "duration": 29200,
            "operator_id": "2",
            "co2": "27.84",
            "segments": []
        },
        {
            "origin_id": "3",
            "destination_id": "8",
            "mode": "train",
            "fare": "80",
            "duration": 19530,
            "operator_id": "3",
            "co2": "69.6",
            "segments": [
                {
                    "origin_id": "3",
                    "destination_id": "8",
                    "mode": "train",
                    "name": "Coast Starlight",
                    "duration": 19530,
                    "operator_id": "3"
                }
            ]
        },
        {
            "origin_id": "4",
            "destination_id": "9",
            "mode": "flight",
            "fare": "120",
            "duration": 4500,
            "operator_id": "4",
            "co2": "104.4",
            "segments": []
        },
        {
            "origin_id": "4",
            "destination_id": "9",
            "mode": "flight",
            "fare": "190",
            "duration": 4500,
            "operator_id": "5",
            "co2": "165.3",
            "segments": []
        },
        {
            "origin_id": "4",
            "destination_id": "10",
            "mode": "flight",
            "fare": "210",
            "duration": 4500,
            "operator_id": "6",
            "co2": "182.7",
            "segments": []
        },
        {
            "origin_id": "4",
            "destination_id": "10",
            "mode": "flight",
            "fare": "221",
            "duration": 4500,
            "operator_id": "7",
            "co2": "192.27",
            "segments": []
        },
        {
            "origin_id": "5",
            "destination_id": "11",
            "mode": "drive",
            "fare": "61",
            "duration": 31341,
            "operator_id": "8",
            "co2": "53.07",
            "segments": []
        }
    ],
    "places": [
        {
            "id": "1",
            "name": "Los Angeles Greyhound Station",
            "name_long": "",
            "city": "Los Angeles",
            "region": "CA",
            "country": "US",
            "lat": 34.034458,
            "lng": -118.23555,
            "geoname_id": ""
        },
        {
            "id": "2",
            "name": "Los Angeles Megabus Station",
            "name_long": "",
            "city": "Los Angeles",
            "region": "CA",
            "country": "US",
            "lat": 34.0520410669,
            "lng": -118.243272703,
            "geoname_id": ""
        },
        {
            "id": "3",
            "name": "LAX",
            "name_long": "Los Angeles Union Station",
            "city": "Los Angeles",
            "region": "CA",
            "country": "US",
            "lat": 34.0562,
            "lng": -118.237,
            "geoname_id": ""
        },
        {
            "id": "4",
            "name": "LAX",
            "name_long": "Los Angeles International Airport",
            "city": "Los Angeles",
            "region": "CA",
            "country": "US",
            "lat": 33.942536,
            "lng": -118.408075,
            "geoname_id": ""
        },
        {
            "id": "5",
            "name": "request_origin",
            "name_long": "",
            "city": "",
            "region": "",
            "country": "",
            "lat": 34.0156082,
            "lng": -118.68505,
            "geoname_id": ""
        },
        {
            "id": "6",
            "name": "San Francisco Greyhound Station",
            "name_long": "",
            "city": "San Francisco",
            "region": "CA",
            "country": "US",
            "lat": 37.78924,
            "lng": -122.39224,
            "geoname_id": ""
        },
        {
            "id": "7",
            "name": "San Francisco Megabus Station",
            "name_long": "",
            "city": "San Francisco",
            "region": "CA",
            "country": "US",
            "lat": 37.77497,
            "lng": -122.398526,
            "geoname_id": ""
        },
        {
            "id": "8",
            "name": "OAC",
            "name_long": "Oakland Coliseum",
            "city": "Oakland",
            "region": "CA",
            "country": "US",
            "lat": 37.7525,
            "lng": -122.198,
            "geoname_id": ""
        },
        {
            "id": "9",
            "name": "SFO",
            "name_long": "San Francisco International Airport",
            "city": "San Francisco",
            "region": "CA",
            "country": "US",
            "lat": 37.618972,
            "lng": -122.374889,
            "geoname_id": ""
        },
        {
            "id": "10",
            "name": "OAK",
            "name_long": "Metropolitan Oakland Intl",
            "city": "Oakland",
            "region": "CA",
            "country": "US",
            "lat": 37.721278,
            "lng": -122.220722,
            "geoname_id": ""
        },
        {
            "id": "11",
            "name": "request_destination",
            "name_long": "",
            "city": "",
            "region": "",
            "country": "",
            "lat": 37.7576793,
            "lng": -122.5076401,
            "geoname_id": ""
        }
    ],
    "operators": [
        {
            "id": "1",
            "name": "Greyhound",
            "logo_img": "\/img\/operators\/greyhound.png",
            "mode": "bus",
            "code": "",
            "attributes": {
                "website": "https:\/\/www.greyhound.com",
                "twitter": "greyhound"
            }
        },
        {
            "id": "2",
            "name": "Megabus",
            "logo_img": "\/img\/operators\/megabus.png",
            "mode": "bus",
            "code": "",
            "attributes": []
        },
        {
            "id": "3",
            "name": "Amtrak",
            "logo_img": "\/img\/operators\/amtrak.png",
            "mode": "train",
            "code": "",
            "attributes": []
        },
        {
            "id": "4",
            "name": "Delta",
            "logo_img": "\/img\/operators\/dl.png",
            "mode": "flight",
            "code": "DL",
            "attributes": []
        },
        {
            "id": "5",
            "name": "United",
            "logo_img": "\/img\/operators\/ua.png",
            "mode": "flight",
            "code": "UA",
            "attributes": []
        },
        {
            "id": "6",
            "name": "American Airlines",
            "logo_img": "\/img\/operators\/aa.png",
            "mode": "flight",
            "code": "AA",
            "attributes": []
        },
        {
            "id": "7",
            "name": "Spirit",
            "logo_img": "\/img\/operators\/nk.png",
            "mode": "flight",
            "code": "NK",
            "attributes": []
        },
        {
            "id": "8",
            "name": "Carpool",
            "logo_img": "\/img\/operators\/carpool.png",
            "mode": "drive",
            "code": "",
            "attributes": []
        }
    ]
}

Route option response

   {
    "origin_id": "1",
    "destination_id": "3",
    "mode": "train",
    "fare": "80",
    "duration": 7060,
    "operator_id": "3",
    "co2": "69.6",
    "segments": [
        {
            "origin_id": "1",
            "destination_id": "2",
            "mode": "train",
            "name": "Coast Starlight",
            "duration": 1530,
            "operator_id": "3"
        },
        {
            "origin_id": "2",
            "destination_id": "3",
            "mode": "train",
            "name": "Capitol Corridor",
            "duration": 5530,
            "operator_id": "3"
        }
    ]
}                    

Operators response

   {
    "id": "1",
    "name": "Greyhound",
    "logo_img": "\/img\/operators\/greyhound.png",
    "mode": "bus",
    "code": "",
    "attributes": {
        "website": "https:\/\/www.greyhound.com",
        "lost_luggage_url": "https:\/\/www.greyhound.com\/en\/help-and-info\/travel-dilemmas\/lost-baggage-info",
        "twitter": "greyhound"
    }
}