CarpoolWorld REST API - Trip match

→ Developers → REST Api

Version:

1.0 2.0

REST API: Trip match

Retrieve a list of trips that match a stored trip

Resource information

https://www.carpoolworld.com/rest_match.html/trip_id#/IOFormat

Request/Response Formats (IOFormat)

XML or JSON

HTTP Methods

POST or GET

Resource description

Use GET https://www.carpoolworld.com/rest_match.html/trip_id#/IOFormat

Resource URL

https://www.carpoolworld.com/rest_match.html/trip_id#/IOFormat

* To get the trip id, use trip_list or specify the trip_id# as 0 to retrieve the latest confirmed trip for that traveler
ex: https://www.carpoolworld.com/rest_match.html/0/JSON

Parameters

partner_name	required	Your developer partner name
partner_key	required	Your developer partner key
traveler_name	required	A traveler name of your choice. Up to 20 characters. Letters (a-z), numbers (0-9) and underscores (_) are allowed
traveler_password	required	A traveler password of your choice, if this is an existing traveler, the passwords must match. The password are stored encrypted in the carpoolworld database Up to 20 characters.
selected_radius_distance_home	optional	Radius to include matches that are in a radius distance from home. Decimal ex: 0.300 is 30km from home see example radius
selected_radius_distance_work	optional	Radius to include matches that are in a radius distance from work. Decimal ex: 0.300 is 30km from work see example radius
selected_radius	optional	Radius to include matches that are in a total radius distance from home + radius distance from work. Decimal ex: 0.600 is 60km from home and work see example radius
selected_radius_your_detour	optional	Radius to include matches that are in a maximum distance for the traveler to pick up other travelers. Decimal ex: 0.100 is 10km maximum detour example radius
selected_radius_his_detour	optional	Radius to include matches that are in a maximum distance for other travelers to pick you up. Decimal ex: 0.100 is 10km maximum detour example radius
selected_origin_time_constraint	optional	Time constraint to include other travelers that start work (or want to be at the destination) within +/- time from your start time. ex: 00:45:00 is a start time 45 minutes from your start time example time constraints
selected_destination_time_constraint	optional	Time constraint to include other travelers that end work (or want to leave the destination) within +/- time from your end time. ex: 01:00:00 is a end time 1 hour from your end time example time constraints
selected_match_car_constraint	optional	Include other travelers that are D=Driver only P=Passenger only B=Either
selected_match_schedule_constraint	optional	Include other travelers that are traveling Y=Regular schedule only N=One time trip only
selected_match_smoke	optional	Include other travelers that specified on their profile their smoking habits 1=Smoker 2=Non-Smoker
selected_match_gender	optional	Include other travelers that specified their gender F=Female M=Male N=Nonbinary
selected_sorting_option	optional	Sort matches first by: distance_between_commutes=total distance between commutes modiff=distance between origin mddiff=distance between destinations searcher_detour=Searcher's detour matchs_detour=Match's detour
selected_match_schedule_date_constraint	optional	Include trips that are +- days from departure date ex: 1 would include trips that depart +/- 1 day from the trip departure date. 0 is for the same departure date
user_match_day1	optional	Include Monday trips 1=Include Monday trips
user_match_day2	optional	Include Tuesday trips 2=Include Tuesday trips
user_match_day3	optional	Include Wednesday trips 3=Include Wednesday trips
user_match_day4	optional	Include Thursday trips 4=Include Thursday trips
user_match_day5	optional	Include Friday trips 5=Include Friday trips
user_match_day6	optional	Include Saturday trips 6=Include Saturday trips
user_match_day7	optional	Include Sunday trips 7=Include Sunday trips

JSON

XML

<<<XML
<trips>
<trip>
<partner_name>demo_group</partner_name>
<partner_key>fdusiu32982pj2wj</partner_key>
<traveler_name>happydriver</traveler_name>
<traveler_password>mysecretpassword123</traveler_password>
<selected_radius_distance_home>0.600</selected_radius_distance_home>
<selected_radius_distance_work></selected_radius_distance_work>
<selected_radius></selected_radius>
<selected_radius_your_detour></selected_radius_your_detour>
<selected_radius_his_detour></selected_radius_his_detour>
<selected_origin_time_constraint>00:45:00</selected_origin_time_constraint>
<selected_destination_time_constraint></selected_destination_time_constraint>
<selected_match_car_constraint>D</selected_match_car_constraint>
<selected_match_schedule_constraint>Y</selected_match_schedule_constraint>
<selected_match_smoke>2</selected_match_smoke>
<selected_match_gender>F</selected_match_gender>
<selected_sorting_option></selected_sorting_option>
<selected_match_schedule_date_constraint></selected_match_schedule_date_constraint>
<user_match_day1>1</user_match_day1>
<user_match_day2></user_match_day2>
<user_match_day3>3</user_match_day3>
<user_match_day4></user_match_day4>
<user_match_day5>5</user_match_day5>
<user_match_day6></user_match_day6>
<user_match_day7></user_match_day7>
</trip>
</trips>
XML;

Responses

The response is formatted as follows

JSON
XML

JSON

{
	"status_detail":
	{
		"status_code":"0000",
		"status_traveler":"happydriver",
		"status_trip":"302445",
		"status_message":"Initialize"
		
	},
	{
	"status_detail": {
		"status_code": "2000",
		"status_traveler": "happydriver",
		"status_trip": "443635",
		"status_message": {
			"matches": {
				"trip": [
					{
						"status": "NEW",
						"url_image": "http:\/\/www.carpoolworld.com\/member_pics\/iboulardhb.png",
						"traveler": "iboulardhb",
						"trip_id": "511808",
						"car": "Passenger",
						"home_city": "Bedminster Township",
						"home_postal_zip": "07921",
						"home_country": "USA,US",
						"home_name": {},
						"work_city": "Bridgewater",
						"work_postal_zip": "08807",
						"work_country": "USA,US",
						"work_name": "Bridgewater Office",
						"olat": "40.6421861",
						"olon": "-74.6423518",
						"dlat": "40.5798190",
						"dlon": "-74.6054020",
						"trip_distance": "8",
						"distance_between_origin": "4",
						"distance_between_destination": "0",
						"distance_between_commute": "4",
						"your_detour": "0",
						"their_detour": "9",
						"mi_or_km": "km",
						"leave_destination_time": "14:30:00",
						"leave_origin_time": "08:00:00",
						"regular_schedule": "Y",
						"day1": "1",
						"day2": "0",
						"day3": "3",
						"day4": "0",
						"day5": "5",
						"day6": "0",
						"day7": "0",
						"days_vary": "Days do not vary",
						"contact_url": "http:\/\/www.carpoolworld.com\/matches_email.html?sfn=269148&sf=happydriver&sr=qkRxMkuvhb&st=443635&su=&to_trip=511808&to=iboulardhb",
						"home_phone": {},
						"work_phone": {},
						"cost_share": "#taketurns, or $25\/week",
						"interested_in_modes": "#carpool",
						"me_viewed": "6",
						"me_accepts": "1",
						"me_declines": "0",
						"me_replies": "17",
						"to_viewed": "2",
						"to_accepts": "0",
						"to_declines": "0",
						"to_replies": "7"
					}, {
						"status": "NEW",
						"url_image": "http:\/\/www.carpoolworld.com\/member_pics\/iboulardt1.jpg",
						"traveler": "iboulardt1",
						"trip_id": "684951",
						"car": "Driver or passenger",
						"home_city": "Lebanon",
						"home_postal_zip": "08833",
						"home_country": "USA,US",
						"home_name": {},
						"work_city": "Bridgewater",
						"work_postal_zip": "08807",
						"work_country": "USA,US",
						"work_name": "Bridgewater Office",
						"olat": "40.6434190",
						"olon": "-74.8334740",
						"dlat": "40.5798190",
						"dlon": "-74.6054020",
						"trip_distance": "21",
						"distance_between_origin": "13",
						"distance_between_destination": "0",
						"distance_between_commute": "13",
						"your_detour": "22",
						"their_detour": "5",
						"mi_or_km": "km",
						"leave_destination_time": "17:00:00",
						"leave_origin_time": "09:00:00",
						"regular_schedule": "Y",
						"day1": "1",
						"day2": "2",
						"day3": "3",
						"day4": "4",
						"day5": "5",
						"day6": "0",
						"day7": "0",
						"days_vary": "Days do not vary",
						"contact_url": "http:\/\/www.carpoolworld.com\/matches_email.html?sfn=269148&sf=happydriver&sr=qkRxMkuvhb&st=443635&su=&to_trip=684951&to=iboulardt1",
						"home_phone": {},
						"work_phone": {},
						"cost_share": {},
						"interested_in_modes": "#carpool",
						"me_viewed": "0",
						"me_accepts": "0",
						"me_declines": "0",
						"me_replies": "0",
						"to_viewed": "0",
						"to_accepts": "0",
						"to_declines": "0",
						"to_replies": "0"
					}
				]
			}
		}
	}
},
    {
		"status_code":"9999",
		"status_traveler":"happydriver",
		"status_trip":"302445",
		"status_message":"Finalize"
    }
    ]
}

XML

<statuses>
<status_detail>
<status_code>0000</status_code>
<status_traveler></status_traveler>
<status_trip>212718</status_trip>
<status_message>Initialize</status_message>
</status_detail>

<statuses>
	<status_detail>
		<status_code>2000</status_code>
		<status_traveler>happydriver</status_traveler>
		<status_trip>443635</status_trip>
		<status_message>
			<matches>
				<trip>
					<hidden>1</hidden>
					<status>NEW</status>
					<url_image>http://www.carpoolworld.com/member_pics/iboulardhb.png</url_image>
					<traveler>iboulardhb</traveler>
					<trip_id>511808</trip_id>
					<car>Passenger</car>
					<home_city>Bedminster Township</home_city>
					<home_postal_zip>07921</home_postal_zip>
					<home_country>USA,US</home_country>
					<home_name></home_name>
					<work_city>Bridgewater</work_city>
					<work_postal_zip>08807</work_postal_zip>
					<work_country>USA,US</work_country>
					<work_name>Bridgewater Office</work_name>
					<olat>40.6421861</olat>
					<olon>-74.6423518</olon>
					<dlat>40.5798190</dlat>
					<dlon>-74.6054020</dlon>
					<trip_distance>8</trip_distance>
					<distance_between_origin>4</distance_between_origin>
					<distance_between_destination>0</distance_between_destination>
					<distance_between_commute>4</distance_between_commute>
					<your_detour>0</your_detour>
					<their_detour>9</their_detour>
					<mi_or_km>km</mi_or_km>
					<leave_destination_time>14:30:00</leave_destination_time>
					<leave_origin_time>08:00:00</leave_origin_time>
					<regular_schedule>Y</regular_schedule>
					<day1>1</day1>
					<day2>0</day2>
					<day3>3</day3>
					<day4>0</day4>
					<day5>5</day5>
					<day6>0</day6>
					<day7>0</day7>
					<days_vary>Days do not vary</days_vary>
					<contact_url>http://www.carpoolworld.com/matches_email.html?sfn=269148&sf=happydriver&sr=qkRxMkuvhb&st=443635&su=&to_trip=511808&to=iboulardhb</contact_url>
					<home_phone></home_phone>
					<work_phone></work_phone>
					<cost_share>#taketurns, or $25/week</cost_share>
					<interested_in_modes>#carpool</interested_in_modes>
					<me_viewed>6</me_viewed>
					<me_accepts>1</me_accepts>
					<me_declines>0</me_declines>
					<me_replies>17</me_replies>
					<to_viewed>2</to_viewed>
					<to_accepts>0</to_accepts>
					<to_declines>0</to_declines>
					<to_replies>7</to_replies>
				</trip>
				<trip>
					<url_image>http://www.carpoolworld.com/member_pics/iboulardd12.png</url_image>
					<traveler>iboulardd12</traveler>
					<trip_id>278175</trip_id>
					<car>Driver or passenger</car>
					<home_city>High Bridge</home_city>
					<home_postal_zip>08829</home_postal_zip>
					<home_country>USA,US</home_country>
					<home_name></home_name>
					<work_city>Bridgewater</work_city>
					<work_postal_zip>08807</work_postal_zip>
					<work_country>USA,US</work_country>
					<work_name>Bridgewater Office</work_name>
					<olat>40.6671460</olat>
					<olon>-74.9010510</olon>
					<dlat>40.5798190</dlat>
					<dlon>-74.6054020</dlon>
					<trip_distance>27</trip_distance>
					<distance_between_origin>19</distance_between_origin>
					<distance_between_destination>0</distance_between_destination>
					<distance_between_commute>19</distance_between_commute>
					<your_detour>34</your_detour>
					<their_detour>4</their_detour>
					<mi_or_km>km</mi_or_km>
					<leave_destination_time>14:30:00</leave_destination_time>
					<leave_origin_time>08:00:00</leave_origin_time>
					<regular_schedule>Y</regular_schedule>
					<day1>1</day1>
					<day2>0</day2>
					<day3>3</day3>
					<day4>0</day4>
					<day5>5</day5>
					<day6>0</day6>
					<day7>0</day7>
					<days_vary>Days do not vary</days_vary>
					<contact_url>http://www.carpoolworld.com/matches_email.html?sfn=269148&sf=happydriver&sr=qkRxMkuvhb&st=443635&su=&to_trip=278175&to=iboulardd12</contact_url>
					<home_phone></home_phone>
					<work_phone>111-1111-11111</work_phone>
					<cost_share></cost_share>
					<interested_in_modes>#carpool</interested_in_modes>
					<me_viewed>0</me_viewed>
					<me_accepts>0</me_accepts>
					<me_declines>0</me_declines>
					<me_replies>0</me_replies>
					<to_viewed>0</to_viewed>
					<to_accepts>0</to_accepts>
					<to_declines>0</to_declines>
					<to_replies>0</to_replies>
				</trip>
			</matches>
		</status_message>
	</status_detail>
</statuses>
<status_detail>
<status_code>9999</status_code>
<status_traveler>happydriver</status_traveler>
<status_trip>212718</status_trip>
<status_message>Finalize</status_message>
</status_detail>
</statuses>

Success or error	Status	Description
	9000	Invalid partner or partner key
	9001	Invalid traveler login
	9002	ERRORlistsallerrors
	0000	Initialize
	2000	Lists the trips that match a stored trip.
	9999	Finalize

List of example radius

Radius value	Radius value in KM	Radius value in Miles
0.003	0.3	0.2
0.005	0.5	0.3
0.01	1	1
0.03	3	2
0.05	5	3
0.07	7	4
0.1	10	6
0.2	20	12
0.3	30	19
0.4	40	25
0.5	50	31
0.6	60	37
0.7	70	43
0.8	80	50
0.9	90	56
1	100	62
2	200	124
3	300	186
4	400	249
5	500	311
6	600	373
7	700	435
8	800	497
9	900	559

Example time constraints

Time value	Time description
24:00:00	Any time
00:00:00	+/- 00:00:00 from match's time
00:15:00	+/- 00:15:00 from match's time
00:30:00	+/- 00:30:00 from match's time
00:45:00	+/- 00:45:00 from match's time
01:00:00	+/- 01:00:00 from match's time
01:15:00	+/- 01:15:00 from match's time
01:30:00	+/- 01:30:00 from match's time
01:45:00	+/- 01:45:00 from match's time
02:00:00	+/- 02:00:00 from match's time
02:15:00	+/- 02:15:00 from match's time
02:30:00	+/- 02:30:00 from match's time
02:45:00	+/- 02:45:00 from match's time
03:00:00	+/- 03:00:00 from match's time
03:15:00	+/- 03:15:00 from match's time
03:30:00	+/- 03:30:00 from match's time
03:45:00	+/- 03:45:00 from match's time
04:00:00	+/- 04:00:00 from match's time
04:15:00	+/- 04:15:00 from match's time
04:30:00	+/- 04:30:00 from match's time
04:45:00	+/- 04:45:00 from match's time
05:00:00	+/- 05:00:00 from match's time
05:15:00	+/- 05:15:00 from match's time
05:30:00	+/- 05:30:00 from match's time
05:45:00	+/- 05:45:00 from match's time
06:00:00	+/- 06:00:00 from match's time
06:15:00	+/- 06:15:00 from match's time
06:30:00	+/- 06:30:00 from match's time
06:45:00	+/- 06:45:00 from match's time
07:00:00	+/- 07:00:00 from match's time
07:15:00	+/- 07:15:00 from match's time
07:30:00	+/- 07:30:00 from match's time
07:45:00	+/- 07:45:00 from match's time
08:00:00	+/- 08:00:00 from match's time
08:15:00	+/- 08:15:00 from match's time
08:30:00	+/- 08:30:00 from match's time
08:45:00	+/- 08:45:00 from match's time
09:00:00	+/- 09:00:00 from match's time
09:15:00	+/- 09:15:00 from match's time
09:30:00	+/- 09:30:00 from match's time
09:45:00	+/- 09:45:00 from match's time
10:00:00	+/- 10:00:00 from match's time
10:15:00	+/- 10:15:00 from match's time
10:30:00	+/- 10:30:00 from match's time
10:45:00	+/- 10:45:00 from match's time
11:00:00	+/- 11:00:00 from match's time
11:15:00	+/- 11:15:00 from match's time
11:30:00	+/- 11:30:00 from match's time
11:45:00	+/- 11:45:00 from match's time
12:00:00	+/- 12:00:00 from match's time
12:15:00	+/- 12:15:00 from match's time
12:30:00	+/- 12:30:00 from match's time
12:45:00	+/- 12:45:00 from match's time
13:00:00	+/- 13:00:00 from match's time
13:15:00	+/- 13:15:00 from match's time
13:30:00	+/- 13:30:00 from match's time
13:45:00	+/- 13:45:00 from match's time
14:00:00	+/- 14:00:00 from match's time
14:15:00	+/- 14:15:00 from match's time
14:30:00	+/- 14:30:00 from match's time
14:45:00	+/- 14:45:00 from match's time
15:00:00	+/- 15:00:00 from match's time
15:15:00	+/- 15:15:00 from match's time
15:30:00	+/- 15:30:00 from match's time
15:45:00	+/- 15:45:00 from match's time
16:00:00	+/- 16:00:00 from match's time
16:15:00	+/- 16:15:00 from match's time
16:30:00	+/- 16:30:00 from match's time
16:45:00	+/- 16:45:00 from match's time
17:00:00	+/- 17:00:00 from match's time
17:15:00	+/- 17:15:00 from match's time
17:30:00	+/- 17:30:00 from match's time
17:45:00	+/- 17:45:00 from match's time
18:00:00	+/- 18:00:00 from match's time
18:15:00	+/- 18:15:00 from match's time
18:30:00	+/- 18:30:00 from match's time
18:45:00	+/- 18:45:00 from match's time
19:00:00	+/- 19:00:00 from match's time
19:15:00	+/- 19:15:00 from match's time
19:30:00	+/- 19:30:00 from match's time
19:45:00	+/- 19:45:00 from match's time
20:00:00	+/- 20:00:00 from match's time
20:15:00	+/- 20:15:00 from match's time
20:30:00	+/- 20:30:00 from match's time
20:45:00	+/- 20:45:00 from match's time
21:00:00	+/- 21:00:00 from match's time
21:15:00	+/- 21:15:00 from match's time
21:30:00	+/- 21:30:00 from match's time
21:45:00	+/- 21:45:00 from match's time
22:00:00	+/- 22:00:00 from match's time
22:15:00	+/- 22:15:00 from match's time
22:30:00	+/- 22:30:00 from match's time
22:45:00	+/- 22:45:00 from match's time
23:00:00	+/- 23:00:00 from match's time
23:15:00	+/- 23:15:00 from match's time
23:30:00	+/- 23:30:00 from match's time
23:45:00	+/- 23:45:00 from match's time