Search API

Major Changes (v1.2 to 1.4)

  • Segments have been completely restructured.
  • Added Alternatives that show transit alternatives (eg: a shuttle instead of a bus).
  • Places, Airlines, Aircrafts, Agencies and Vehicles are now referenced via index (instead of a unique code).
  • Agencies no longer have a code.
  • Indicative prices now include price levels (eg: first class, second class) and ranges (low, high).
  • Search flags are now specified by name

Documentation for Search API version 1.2 is available here.

NOTE: Rome2rio does not provide live transit prices or airfares through this API. We recommend using the Skyscanner Flights API for this feature.
Other options for airfare API’s include Expedia, DoHop, eDreams or Vayama.

Example Request

http://free.rome2rio.com/api/1.4/xml/Search?key=&oName=Bern&dName=Zurich&noRideshare
http://free.rome2rio.com/api/1.4/json/Search?key=&oName=Bern&dName=Zurich&noRideshare

SearchRequest

NameTypeDescription
keystring API key
oNamestring Origin display name (optional) [1]
dNamestring Destination display name (optional) [1]
oPosPositionOrigin latitude, longitude (optional) [1]
dPosPositionDestination latitude, longitude (optional) [1]
oKindstringOrigin kind (optional) [2]
dKindstringDestination kind (optional) [2]
currencyCodestringLanguage code (ISO 639-1) (optional) [4]
languageCodestringLanguage code (ISO 639-1) (optional) [4]
datastringCaller supplied data string (optional) [5]
noAirboolExclude air segments (optional)
noAirLeg boolExclude air legs (outbound and return) (optional)
noRailboolExclude train, tram and subway segments (optional)
noBusboolExclude bus segments (optional)
noFerryboolExclude ferry segments (optional)
noCarboolExclude drive and taxi segments (optional)
noBikeshareboolExclude bike share segments (optional)
noRideshareboolExclude ride share segments (eg: BlahBlahCar) (optional)
noTowncarboolExclude towncar segments (eg: Uber) (optional)
noCommuterboolExclude commuter segments (eg: local buses) (optional)
noSpecialboolExclude special segments (eg: steam trains) (optional)
noMinorStartboolExclude minor start segments (eg: train to airport) (optional)
noMinorEndboolExclude minor end segments (eg: train from airport) (optional)
noPathboolExclude paths (optional)
noPriceboolExclude indicative prices (optional)
noStopboolExclude intermediate stops (optional)

[1] If oPos/dPos are not specified, oName/dName are geocoded into latitude and longitude.
[2] The kind determines how precisely the origin and destination should be treated when searching. For example, a value of "city" indicates the position is not very precise and the results should favour major transit hubs in the city. A value of "street_address" means the position is very precise and walking directions should be given. Supported values include Rome2rio Place kinds, Google Geocoding result types and Yahoo WOEID place types.
[3] The three letter currency code is used to format indicative prices. USD is assumed by default.
[4] The two letter language code is used to translate the response. It is also used as a hint in the geocoder. EN is assumed by default.
[5] The data string gets echoed in the response. This can be used by the caller to match responses to requests.

SearchResponse

NameTypeDescription
elapsedTime stringTime to process request (in milliseconds)
currencyCodestringResponse currency code (ISO 4217)
languageCodestringResponse language code (ISO 639-1)
datastringCaller supplied data string (optional)
placesPlace[]Array of places [1]
airlinesAirline[]Array of airlines
aircraftsAircraft[]Array of aircrafts
agenciesAgency[]Array of transit agencies
vehiclesVehicle[]Array of transit vehicles
routesRoute[]Array of routes

[1] places[0] represents the resolved oName, while places[1] represents the resolved dName.
Errors are returned via the following HTTP status codes. The Error-Message header will contain information to diagnose the error.

400 Bad Request: A required parameter is missing or not formatted correctly.
401 Unauthorized: The key specified is not valid.
402 Payment Required: The free server allows 100,000 requests per month. Exceeding this limit results in this response. This limit is reset every month.
429 Too Many Requests: The free server allows 300 requests per hour. Exceeding this limit results in this response. This limit is reset every hour.
444 No Response: Either oName or dName could not be resolved.
500 Server Error: And internal error has occured. This error should never happen and should be reported to us.

Place

NameTypeDescription
latfloatLatitude (WGS84)
lngfloatLongitude (WGS84)
kindstringType of place [1]
shortNamestringDisplay name
codestringAirport or Station code (eg: IATA)
regionCodestringRegion code (ISO 3166-2 or FIPS) (optional)
countryCodestringCountry code (ISO 3166-1 alpha-2) (optional)
timeZonestringTime zone (IANA) (optional)

[1] See Rome2rio Place kinds for example values.

Airline

NameTypeDescription
codestringAirline code (IATA)
namestringDisplay name
urlstringAirline URL (optional)
iconIconAirline icon (optional)

Aircraft

NameTypeDescription
codestringAircraft code (IATA)
manufacturerstringManufacturer name
modelstringModel name

Agency

NameTypeDescription
namestringDisplay name
urlstringAgency URL (optional)
phonestringAgency Phone Number (optional)
iconIconAgency icon (optional)

Vehicle

NameTypeDescription
namestringVehicle display name
kindstringVehicle kind [1]

[1] The following kinds are supported: unknown, plane, helicopter, car, bus, taxi, rideshare, shuttle, towncar, train, tram, cablecar, subway, ferry, foot, animal, bicycle. Please note that this list will likely change in future revisions.

Route

NameTypeDescription
namestringRoute display name
depPlaceintegerDeparture place (index into places array)
arrPlaceintegerArrival place (index into places array)
distancefloatEstimated total distance (in km)
totalDurationfloatEstimated total duration (in minutes, includes transfers)
totalTransitDurationfloatEstimated total duration spent in transit (in minutes)
totalTransferDurationfloatEstimated total duration spent waiting for transfers (in minutes)
indicativePrices IndicativePrice[]Array of indicative prices (optional)
segments Segment[]Array of segments
alternatives Alternative[]Array of alternative segments (optional)

Segment (SurfaceSegment, AirSegment)

NameTypeDescription
segmentKindstringSegment kind [1]
depPlaceintegerDeparture airport (index into places array)
arrPlaceintegerArrival airport (index into places array)
vehicleintegerVehicle (index into vehicles array)
distancefloatEstimated distance (in km)
transitDurationfloatEstimated duration spent in transit (in minutes)
transferDurationfloatEstimated duration spent waiting for transfer (in minutes)
indicativePrices IndicativePrice[]Array of indicative prices (optional)

[1] Either "surface" or "air".

SurfaceSegment: Segment

NameTypeDescription
segmentKindstring"surface"
depPlaceintegerDeparture airport (index into places array)
arrPlaceintegerArrival airport (index into places array)
vehicleintegerVehicle (index into vehicles array)
distancefloatEstimated distance (in km)
transitDurationfloatEstimated duration spent in transit (in minutes)
transferDurationfloatEstimated duration spent waiting for transfer (in minutes)
pathPathPath followed by vehicle/pedestrian (optional)
indicativePrices IndicativePrice[]Array of indicative prices (optional)
stops SurfaceStop[]Array of intermediate stops (optional)
agenciesSurfaceAgency[]Array of agencies (optional)

AirSegment : Segment

NameTypeDescription
segmentKindstring"air"
depPlaceintegerDeparture airport (index into places array)
arrPlaceintegerArrival airport (index into places array)
vehicleintegerVehicle (index into vehicles array)
distancefloatEstimated distance (in km)
transitDurationfloatEstimated duration spent in transit (in minutes)
transferDurationfloatEstimated duration spent waiting for transfer (in minutes)
indicativePrices IndicativePrice[]Array of indicative prices (optional)
outbound AirLeg[]Array of outbound legs
return AirLeg[]Array of return legs

Alternative

NameTypeDescription
firstSegmentintegerFirst segment to replace (index into segments array) [1]
lastSegmentintegerLast segment to replace (index into segments array) [1]
routeRouteAlternative route

[1] The alternative route replaces a set of segments. For example, two bus segments may be replaced by a single drive alternative. Or a single train segment may be replaced by a set of tram alternatives.

SurfaceStop

NameTypeDescription
place integerPlace (index into places array)
transitDurationfloatEstimated duration spent in transit (in minutes)
stopDurationfloatEstimated duration spent waiting at stop before departing (in minutes)

SurfaceAgency

NameTypeDescription
agencyintegerAgency (index into agencies array)
frequencyfloatEstimated frequency (per week) (optional)
durationfloatEstimated duration (in minutes) (optional)
operatingDaysDayFlagsDays of operation bitmask (optional)
lineNames SurfaceLineName[]Array of line names (optional) [1]
lineCodes SurfaceLineCode[]Array of line codes (optional) [1]
links ExternalLink[]Array of links (optional)

[1] When using json encoding, names and codes are serialized as an array of strings.

SurfaceLineName

NameTypeDescription
namestringDisplay name or number

SurfaceLineCode

NameTypeDescription
code stringInternal line code

AirLeg

NameTypeDescription
operatingDaysDayFlagsDays of operation bitmask (optional)
indicativePrices IndicativePrice[]Array of indicative prices (optional)
hops AirHop[]Array of hops

AirHop

NameTypeDescription
depPlaceintegerDeparture airport (index into places array)
arrPlaceintegerArrival airport (index into places array)
depTerminalstringDeparture airport terminal (optional)
arrTerminalstringArrival airport terminal (optional)
depTimestringDeparture time (24-hour local time - hh:mm)
arrTimestringArrival time (24-hour local time - hh:mm)
flightstringFlight number
duration floatEstimated flight duration (in minutes)
airlinestringAdvertised airline (index into airlines array)
operatingAirlinestringOperating airline (index into airlines array)
aircraftstringAircraft (index into airlines array) (optional)
dayChangeintegerNum day changes during flight (optional)
layoverDurationfloatLayover time (in minutes) (optional)
layoverDayChangeintegerNum day changes during layover (optional)
codeshares AirCodeshare[]Array of codeshares (optional)

AirCodeshare

NameTypeDescription
airlineintegerAirline (index into airlines array)
flightstringFlight number

ExternalLink

NameTypeDescription
textstringLink text
urlstringLink URL
displayUrlstringDisplay URL (cleaned up link url) (optional)
moustacheUrlstringMoustach URL (link url with replacement parameters) (optional)

IndicativePrice

NameTypeDescription
namestringDisplay name of price level (optional)
pricefloatMedian price
priceLowfloatLower bound of price range (optional)
priceHighfloatUpper bound of price range (optional)
currencystringCurrency code (ISO 4217)
nativePricefloatMedian price in native currency (optional)
nativePriceLowfloatLower bound of price range in native currency (optional)
nativePriceHighfloatUpper bound of price range in native currency (optional)
nativeCurrencystringNative currency code (ISO 4217) (optional)

If the estimated price is a single value (not a range) then only price is returned.

If the estimated price is a range, then both price and priceLow/priceHigh are returned. You can choose to display either the single price (for brevity) or the range (for accuracy).

Icon

NameTypeDescription
urlstringRelative URL path of icon image
xintegerHorizontal offset of icon in image (in pixels)
yintegerVertical offset of icon in image (in pixels)
wintegerWidth of icon in image (in pixels)
hintegerHeight of icon in image (in pixels)

Position

NameType Description
latfloatLatitude (WGS84)
lngfloatLongitude (WGS84)

[1] Positions are encoded as a comma seprated string (eg: "51.5324,-0.12729").

Boolean

A Boolean is encoded as an integer, where 0 = false and 1 = true.

Path

A Path string represents a series of Positions encoded using the Google Maps Polyline algorithm. Click here for more information.

This string can be passed to the Google Maps API verbatim (ie: decoding is not necessary). However, if you wish to plot the path on a competing map product, you may need to decode the string into Lat/Lng pairs. Please contact us if you would like assistance with this decoding.

DayFlags

ValueDescription
0x01Sunday
0x02Monday
0x04Tuesday
0x08Wednesday
0x10Thursday
0x20Friday
0x40Saturday

Weekdays: 0x3E (0x02 + 0x04 + 0x08 + 0x10 + 0x20)
Weekends: 0x41 (0x01 + 0x40)
Every day: 0x7F

Sign up to use Rome2rio free on your web site or mobile app today.


Sign up Now