Search API (1.2)

Major Changes (v1.0 to 1.2)

  • GetRoutes was renamed to Search.
  • SavedTrip was renamed to SearchResponse (impacts XML encoding only).
  • SearchResponse contains Agencies.
  • Route has new name, distance, duration and stop properties.
  • WalkSegment/CarSegment has new path property.
  • Path property was moved from TransitHop to TransitSegment.
  • Path property is encoded to reduce transmission size.
  • TransitHop contains an array of lines, and most properties were moved to TransitLine.
  • TransitLine agency is an Agency code, as opposed to the display name.

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

{
  "agencies":
    [{
    "code":       "SWISSRAILWAYS",
    "name":       "Swiss Railways (SBB/CFF/FFS)",
    "url":        "http://www.sbb.ch"
    "iconPath":   "/logos/trains/ch.png",
    "iconSize":   "27,23",
    "iconOffset": "0,0"
    ]},
  "routes":
    [{
    "name":     "Train",
    "distance": 95.92,
    "duration": 56,
    "stops":
      [{
      "name": "Bern",
      "pos":  "46.94926,7.43883",
      "kind": "station"
      },{
      "name": "Zürich HB",
      "pos":  "47.37819,8.54019",
      "kind": "station"
      }],
    "segments":
      [{
      "kind":     "train",
      "subkind":     "train",
      "isMajor":  1,
      "distance": 95.92,
      "duration": 56,
      "sName":    "Bern",
      "sPos":     "46.94938,7.43927",
      "tName":    "Zürich HB",
      "tPos":     "47.37819,8.54019",
      "path":     "{wp}Gu{kl@wb@uVo|AqiDyoBhUibDeiDc`AsmDaxBqk@wwA...",
      "indicativePrice":{
        "price":45,
        "currency":"USD",
        "isFreeTransfer":0,
        "nativePrice":40,
        "nativeCurrency":"CHF"
      },
      "itineraries":
        [{
        "legs":
          [{
          "url": "http://fahrplan.sbb.ch/bin/query.exe/en...",
          "hops":
            [{
            "distance":  95.92,
            "duration":  56,
            "sName":     "Bern",
            "sPos":      "46.94938,7.43927",
            "tName":     "Zürich HB",
            "tPos":      "47.37819,8.54019",
            "frequency": 400,
            "indicativePrice":{
              "price":45,
              "currency":"USD",
              "isFreeTransfer":0,
              "nativePrice":40,
              "nativeCurrency":"CHF"
            },
            "lines":
              [{
              "name":      "",
              "vehicle":   "train",
              "agency":    "SWISSRAILWAYS",
              "frequency": 400,
              "duration":  57,
              }]
            }]
          }]
        }]
      }]
    }]
  }]
}

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]
currencyCodestringCurrency code (ISO 4217) (optional) [3]
languageCodestringLanguage code (ISO 639-1) (optional) [4]
FlagsSearchRequestFlagsBitmask of request flags (optional)
datastringCaller supplied data string (optional) [5]

[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 requests and responses.

SearchResponse

NameTypeDescription
placesPlace[]Origin and destination
airportsAirport[]Array of airports
airlinesAirline[]Array of airlines
aircraftsAircraft[]Array of aircrafts
agenciesAgency[]Array of transit agencies
routesRoute[]Array of routes from origin to destination
datastringCaller supplied data string (optional)

Place

NameTypeDescription
kindstringPlace kind [1]
namestringDisplay name
longNamestringFully qualified name
posPositionLatitude,longitude
countryCodestringCountry code (ISO 3166-1 alpha-2) (optional)
regionCodestringRegion code (ISO 3166-2 or FIPS) (optional)
timeZonestringTime zone (IANA) (optional)

[1] See Rome2rio Place kinds for example values.

Airline

NameTypeDescription
codestringAirline code (IATA)
namestringDisplay name
urlstringAirline URL (optional)
iconPathstringRelative URL path of icon image (optional)
iconSizeSizeSize of icon in image (optional)
iconOffsetOffsetOffset of icon in image (optional)

Aircraft

NameTypeDescription
codestringAircraft code (IATA)
manufacturerstringManufacturer name
modelstringModel name

Agency

NameTypeDescription
codestringAgency code
namestringDisplay name
urlstringAgency URL (optional)
iconPathIconRelative URL path of icon image (optional)
iconSizeSizeSize of icon in image (optional)
iconOffsetOffsetOffset of icon in image (optional)

Route

NameTypeDescription
namestringRoute display name
distancefloatEstimated total distance (in km)
durationfloatEstimated total duration (in minutes)
stopsStop[]Array of stops
segments Segment[]Array of segments

Stop

NameTypeDescription
kindstringStop kind [1]
namestringStop display name
posPositionStop latitude/longitude
codestringStop code (eg: airport or station code) (optional)
countryCodestringCountry code (ISO 3166-1 alpha-2) (optional)
regionCodestringRegion code (ISO 3166-2 or FIPS) (optional)
timeZonestringTime zone (IANA) (optional)

[1] See Rome2rio Place kinds for example values.

WalkSegment, CarSegment

NameTypeDescription
kindstring"walk", "car"
vehiclestringVehicle display name
isMajorBooleanIs this a dominant segment in the route?
isImperialBooleanIs this segment in a location where imperial unit are used (eg: miles)?
distancefloatEstimated distance (in km)
durationfloatEstimated duration (in minutes)
sNamestringSource display name
sPosPositionSource latitude/longitude
tNamestringTarget display name
tPosPositionTarget latitude/longitude
indicativePriceIndicativePriceIndicative price
pathPathPath followed by vehicle/pedestrian

TransitSegment

NameTypeDescription
kindstring"train", "bus", "ferry"
subkindstringMore specific for new transit types, eg. "train", "bus", "ferry", "carferry", "cablecar", "helicopter"
isMajorBooleanIs this a dominant segment in the route?
isImperialBooleanIs this segment in a location where imperial unit are used (eg: miles)?
distancefloatEstimated distance (in km)
durationfloatEstimated duration (in minutes)
sNamestringSource display name
sPosPositionSource latitude/longitude
tNamestringTarget display name
tPosPositionTarget latitude/longitude
indicativePriceIndicativePriceIndicative price
itinerariesTransitItinerary[]Array of alternative transit itineraries
pathPathPath followed by vehicle

TransitItinerary

NameTypeDescription
legsTransitLeg[]Array of transit legs

TransitLeg

NameTypeDescription
urlstringSchedule URL (optional)
hopsTransitHopArray of transit hops

TransitHop

NameTypeDescription
sNamestringSource display name
sPosPositionSource latitude/longitude
tNamestringTarget display name
tPosPositionTarget latitude/longitude
frequencyfloatEstimated feequency (per week)
durationfloatEstimated duration (in minutes)
indicativePriceIndicativePriceIndicative price
linesTransitLine[]Array of transit lines

TransitLine

NameTypeDescription
namestringLine display name
vehiclestringVehicle display name
codestringLine code (optional)
agencystringAgency code (optional)
frequencyfloatEstimated frequency (per week)
durationfloatEstimated duration (in minutes)
daysDayFlagsDays of operation bitmask (optional)

FlightSegment

NameTypeDescription
kindstring"flight"
isMajorBooleanIs this a dominant segment in the route?
distancefloat Estimated distance (in km)
durationfloat Estimated duration (in minutes)
sCodestringSource airport code (IATA)
tCodestringTarget airport code (IATA)
indicativePriceIndicativePriceIndicative price
itinerariesFlightItinerary[]Array of alternative flight itineraries

FlightLeg

NameTypeDescription
daysDayFlagsDays of operation bitmask
hopsFlightHop[]Array of flight hops

FlightHop

NameTypeDescription
sCodestringSource airport code (IATA)
tCodestringTarget airport code (IATA)
sTerminalstringSource airport terminal (optional)
tTerminalstringTarget airport terminal (optional)
sTimestringDeparture time (24-hour local time - hh:mm)
tTimestringArrival time (24-hour local time - hh:mm)
airlinestringAirline code (IATA)
flightstringFlight number
durationfloatEstimated flight duration (in minutes)
aircraftstringAircraft code (IATA) (optional)
dayChangeintegerNum day changes during flight (optional)
lDurationfloatLayover time (in minutes) (optional)
lDayChangeintegerNum day changes during layover (optional)
codesharesCodeshare[]Array of codeshares (optional)

Codeshare

NameTypeDescription
airlineintegerAirline code (IATA)
flightstringFlight number

IndicativePrice

NameTypeDescription
pricefloatIndicative price (optional)
currencystringCurrency code (ISO 4217) (optional)
nativePricefloatMedian price in native currency (optional)
nativeCurrencystringNative currency code (ISO 4217) (optional)
isFreeTransferBooleanIs this price zero due to a transfer? (optional)

Position

NameType Description
latfloatLatitude (WGS84)
lngfloatLongitude (WGS84)

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

Size

NameTypeDescription
wfloatWidth (in pixels)
hfloatHeight (in pixels)

[1] Sizes are encoded as a comma seprated string (eg: "27,23").

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

Offset

NameTypeDescription
xfloatX (in pixels)
yfloatY (in pixels)

[1] Offsets are encoded as a comma seprated string (eg: "0,183").

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


Sign up Now