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

Name	Type	Description
key	string	API key
oName	string	Origin display name (optional) [1]
dName	string	Destination display name (optional) [1]
oPos	Position	Origin latitude, longitude (optional) [1]
dPos	Position	Destination latitude, longitude (optional) [1]
oKind	string	Origin kind (optional) [2]
dKind	string	Destination kind (optional) [2]
currencyCode	string	Language code (ISO 639-1) (optional) [4]
languageCode	string	Language code (ISO 639-1) (optional) [4]
data	string	Caller supplied data string (optional) [5]
noAir	bool	Exclude air segments (optional)
noAirLeg	bool	Exclude air legs (outbound and return) (optional)
noRail	bool	Exclude train, tram and subway segments (optional)
noBus	bool	Exclude bus segments (optional)
noFerry	bool	Exclude ferry segments (optional)
noCar	bool	Exclude drive and taxi segments (optional)
noBikeshare	bool	Exclude bike share segments (optional)
noRideshare	bool	Exclude ride share segments (eg: BlahBlahCar) (optional)
noTowncar	bool	Exclude towncar segments (eg: Uber) (optional)
noCommuter	bool	Exclude commuter segments (eg: local buses) (optional)
noSpecial	bool	Exclude special segments (eg: steam trains) (optional)
noMinorStart	bool	Exclude minor start segments (eg: train to airport) (optional)
noMinorEnd	bool	Exclude minor end segments (eg: train from airport) (optional)
noPath	bool	Exclude paths (optional)
noPrice	bool	Exclude indicative prices (optional)
noStop	bool	Exclude 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

Name	Type	Description
elapsedTime	string	Time to process request (in milliseconds)
currencyCode	string	Response currency code (ISO 4217)
languageCode	string	Response language code (ISO 639-1)
data	string	Caller supplied data string (optional)
places	Place[]	Array of places [1]
airlines	Airline[]	Array of airlines
aircrafts	Aircraft[]	Array of aircrafts
agencies	Agency[]	Array of transit agencies
vehicles	Vehicle[]	Array of transit vehicles
routes	Route[]	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

Name	Type	Description
lat	float	Latitude (WGS84)
lng	float	Longitude (WGS84)
kind	string	Type of place [1]
shortName	string	Display name
code	string	Airport or Station code (eg: IATA)
regionCode	string	Region code (ISO 3166-2 or FIPS) (optional)
countryCode	string	Country code (ISO 3166-1 alpha-2) (optional)
timeZone	string	Time zone (IANA) (optional)

[1] Currently, the following kinds are supported: unknown, continent, country, admin3, admin2, admin1, island, village, town, city, capital, metropolis, megalopolis, landmark, place, road, accommodation, station, airport, seaport, sea, lake and river. Please note that this list will likely change in future revisions.

Airline

Name	Type	Description
code	string	Airline code (IATA)
name	string	Display name
url	string	Airline URL (optional)
icon	Icon	Airline icon (optional)

Aircraft

Name	Type	Description
code	string	Aircraft code (IATA)
manufacturer	string	Manufacturer name
model	string	Model name

Agency

Name	Type	Description
name	string	Display name
url	string	Agency URL (optional)
phone	string	Agency Phone Number (optional)
icon	Icon	Agency icon (optional)

Vehicle

Name	Type	Description
name	string	Vehicle display name
kind	string	Vehicle 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

Name	Type	Description
name	string	Route display name
depPlace	integer	Departure place (index into places array)
arrPlace	integer	Arrival place (index into places array)
distance	float	Estimated total distance (in km)
totalDuration	float	Estimated total duration (in minutes, includes transfers)
totalTransitDuration	float	Estimated total duration spent in transit (in minutes)
totalTransferDuration	float	Estimated 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)

Name	Type	Description
segmentKind	string	Segment kind [1]
depPlace	integer	Departure airport (index into places array)
arrPlace	integer	Arrival airport (index into places array)
vehicle	integer	Vehicle (index into vehicles array)
distance	float	Estimated distance (in km)
transitDuration	float	Estimated duration spent in transit (in minutes)
transferDuration	float	Estimated duration spent waiting for transfer (in minutes)
indicativePrices	IndicativePrice[]	Array of indicative prices (optional)

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

SurfaceSegment: Segment

Name	Type	Description
segmentKind	string	"surface"
depPlace	integer	Departure airport (index into places array)
arrPlace	integer	Arrival airport (index into places array)
vehicle	integer	Vehicle (index into vehicles array)
distance	float	Estimated distance (in km)
transitDuration	float	Estimated duration spent in transit (in minutes)
transferDuration	float	Estimated duration spent waiting for transfer (in minutes)
path	Path	Path followed by vehicle/pedestrian (optional)
indicativePrices	IndicativePrice[]	Array of indicative prices (optional)
stops	SurfaceStop[]	Array of intermediate stops (optional)
agencies	SurfaceAgency[]	Array of agencies (optional)

AirSegment : Segment

Name	Type	Description
segmentKind	string	"air"
depPlace	integer	Departure airport (index into places array)
arrPlace	integer	Arrival airport (index into places array)
vehicle	integer	Vehicle (index into vehicles array)
distance	float	Estimated distance (in km)
transitDuration	float	Estimated duration spent in transit (in minutes)
transferDuration	float	Estimated 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

Name	Type	Description
firstSegment	integer	First segment to replace (index into segments array) [1]
lastSegment	integer	Last segment to replace (index into segments array) [1]
route	Route	Alternative 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

Name	Type	Description
place	integer	Place (index into places array)
transitDuration	float	Estimated duration spent in transit (in minutes)
stopDuration	float	Estimated duration spent waiting at stop before departing (in minutes)

SurfaceAgency

Name	Type	Description
agency	integer	Agency (index into agencies array)
frequency	float	Estimated frequency (per week) (optional)
duration	float	Estimated duration (in minutes) (optional)
operatingDays	DayFlags	Days 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

Name	Type	Description
name	string	Display name or number

SurfaceLineCode

Name	Type	Description
code	string	Internal line code

AirLeg

Name	Type	Description
operatingDays	DayFlags	Days of operation bitmask (optional)
indicativePrices	IndicativePrice[]	Array of indicative prices (optional)
hops	AirHop[]	Array of hops

AirHop

Name	Type	Description
depPlace	integer	Departure airport (index into places array)
arrPlace	integer	Arrival airport (index into places array)
depTerminal	string	Departure airport terminal (optional)
arrTerminal	string	Arrival airport terminal (optional)
depTime	string	Departure time (24-hour local time - hh:mm)
arrTime	string	Arrival time (24-hour local time - hh:mm)
flight	string	Flight number
duration	float	Estimated flight duration (in minutes)
airline	string	Advertised airline (index into airlines array)
operatingAirline	string	Operating airline (index into airlines array)
aircraft	string	Aircraft (index into airlines array) (optional)
dayChange	integer	Num day changes during flight (optional)
layoverDuration	float	Layover time (in minutes) (optional)
layoverDayChange	integer	Num day changes during layover (optional)
codeshares	AirCodeshare[]	Array of codeshares (optional)

AirCodeshare

Name	Type	Description
airline	integer	Airline (index into airlines array)
flight	string	Flight number

ExternalLink

Name	Type	Description
text	string	Link text
url	string	Link URL
displayUrl	string	Display URL (cleaned up link url) (optional)
moustacheUrl	string	Moustach URL (link url with replacement parameters) (optional)

IndicativePrice

Name	Type	Description
name	string	Display name of price level (optional)
price	float	Median price
priceLow	float	Lower bound of price range (optional)
priceHigh	float	Upper bound of price range (optional)
currency	string	Currency code (ISO 4217)
nativePrice	float	Median price in native currency (optional)
nativePriceLow	float	Lower bound of price range in native currency (optional)
nativePriceHigh	float	Upper bound of price range in native currency (optional)
nativeCurrency	string	Native 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

Name	Type	Description
url	string	Relative URL path of icon image
x	integer	Horizontal offset of icon in image (in pixels)
y	integer	Vertical offset of icon in image (in pixels)
w	integer	Width of icon in image (in pixels)
h	integer	Height of icon in image (in pixels)

Position

Name	Type	Description
lat	float	Latitude (WGS84)
lng	float	Longitude (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

Value	Description
0x01	Sunday
0x02	Monday
0x04	Tuesday
0x08	Wednesday
0x10	Thursday
0x20	Friday
0x40	Saturday

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