{"__v":8,"_id":"564bcf5402c94e0d00a7e8ba","category":{"__v":3,"_id":"564bcf5e8b1c5521002bb91e","pages":["564bd130f2a98421005f79a1","568ff61804440a1700e4cbc7","569f0b15ffccd10d00a05ccd"],"project":"5617f98f7f74330d00dfd86d","version":"564bcf5302c94e0d00a7e8b0","reference":false,"createdAt":"2015-11-18T01:07:42.887Z","from_sync":false,"order":4,"slug":"api-tutorials","title":"API Tutorials"},"parentDoc":null,"project":"5617f98f7f74330d00dfd86d","user":"5617f95d7f74330d00dfd86c","version":{"__v":10,"_id":"564bcf5302c94e0d00a7e8b0","project":"5617f98f7f74330d00dfd86d","hasDoc":true,"hasReference":true,"createdAt":"2015-11-18T01:07:31.166Z","releaseDate":"2015-11-18T01:07:31.166Z","categories":["564bcf5402c94e0d00a7e8b1","564bcf5402c94e0d00a7e8b2","564bcf5402c94e0d00a7e8b3","564bcf5e8b1c5521002bb91e","564bcfa12c4e3a3500f91237","564bcfaa02c94e0d00a7e8d1","564bcfb542e6862300fc7719","564cc3165058252100ce8fa0","565ca2a0ea82b00d00f94a30","56983c4fbacbc30d00b5b332","56e0eb865ad55a2000743cfa","56e0eb9bd00f551900c8a957"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.1.0","version":"1.1"},"updates":[],"createdAt":"2015-10-29T17:35:36.102Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"Getting Started\n===============\n\nThe tutorials on this page will get you going with the Uber API in no time. Please check out our [SDKs](https://developer.uber.com/docs/sdks) for working sample applications.\n\nBefore you start, you will have to register an application with us [here]. You will need to provide us with your application name and a description, and we will provide you with a `client_id`, `secret`, and `server_token`. If your application requires any user information, be sure to check off the relevant scopes and authorize via [OAuth].\n\nServer Side Authentication\n==========================\n\nThe server side authentication tutorial will go through using the Uber API endpoints for requests that do not require a user login. These endpoints include:\n\n``` sourceCode\nGET /v1/products\nGET /v1/estimates/time\nGET /v1/estimates/price\n```\n\n [here]: https://developer.uber.com/dashboard/\n [OAuth]: #section-oauth-2-0\n\nMaking a Request\n================\n\nThis is an example request made with server\\_token authentication. In this example, we are making a call to the products endpoint which will return all of the Uber products that are available at the specified latitude and longitude.\n\n``` sourceCode\nimport requests\n\nurl = 'https://api.uber.com/v1/products'\n\nparameters = {\n 'server_token': 'INSERT_SERVER_TOKEN_HERE',\n 'latitude': 37.775818,\n 'longitude': -122.418028,\n}\n\nresponse = requests.get(url, params=parameters)\n\ndata = response.json()\n```\n\n\nOAuth 2.0\n=========\n\nThe server OAuth tutorial will go through using the Uber API endpoints for requests that require permission of an authenticated user. The Uber API uses OAuth 2.0 and for this Python example we will use the third-party libraries OAuth2Service (from the [rauth]) and [requests].\n\nThe endpoints that require OAuth include:\n\n``` sourceCode\nGET /v1/me\nGET /v1.1/history\nGET /v1/requests\n```\n\n**Step 1**\n\nHave the user sign in, authorizing your app to access their Uber account.\n\n``` sourceCode\nfrom rauth import OAuth2Service\n\n uber_api = OAuth2Service(\n client_id='INSERT_CLIENT_ID',\n client_secret='INSERT_CLIENT_SECRET',\n name='INSERT_APP_NAME',\n authorize_url='https://login.uber.com/oauth/authorize',\n access_token_url='https://login.uber.com/oauth/token',\n base_url='https://api.uber.com/v1/',\n )\n\nparameters = {\n 'response_type': 'code',\n 'redirect_uri': 'INSERT_ROUTE_TO_STEP_TWO',\n 'scope': 'profile',\n}\n\n# Redirect user here to authorize your application\nlogin_url = uber_api.get_authorize_url(**parameters)\n```\n\n [rauth]: http://rauth.readthedocs.org/en/latest/\n [requests]: http://docs.python-requests.org/en/latest/\n\n**Step 2**\n\nAfter you have authorized, the authorization code will be exchanged for an access token. This access token will be required for calling the different parts of the API.\n\n``` sourceCode\nimport requests\n\n# Once your user has signed in using the previous step you should redirect\n# them here\n\nparameters = {\n 'redirect_uri': 'INSERT_ROUTE_TO_STEP_TWO',\n 'code': request.args.get('code'),\n 'grant_type': 'authorization_code',\n}\n\nresponse = requests.post(\n 'https://login.uber.com/oauth/token',\n auth=(\n 'INSERT_CLIENT_ID',\n 'INSERT_CLIENT_SECRET',\n ),\n data=parameters,\n)\n\n# This access_token is what we'll use to make requests in the following\n# steps\naccess_token = response.json().get('access_token')\n```\n\n\nThe access token is what you will need to make requests on behalf of the logged in user. You should store this token securely, so that the user will not have to go through the authorization process again.\n\n**Step 3**\n\nNow that we have an access token, we will be able to make requests to the Uber API. The following is an example call to the `/v1/me` endpoint that will return user information about the authorized user.\n\n**Request**\n\n``` sourceCode\nurl = 'https://api.uber.com/v1/me'\nresponse = requests.get(\n url,\n headers={\n 'Authorization': 'Bearer %s' % access_token\n }\n)\ndata = response.json()\n```\n\n\nHere is an example of the data that would have been returned form the previous step:\n\n**Response**\n\n``` sourceCode\n{\n \"first_name\": \"Uber\",\n \"last_name\": \"Developer\",\n \"email\": \"developer:::at:::uber.com\",\n \"picture\": \"https://...\",\n \"promo_code\": \"teypo\"\n}\n```\n\n**Authentication and Sign Up Flow**\n\n![OAuth2.0 Connection]\n\n[OAuth2.0 Connection]: https://d1a3f4spazzrp4.cloudfront.net/developer.uber.com/_static/images/tutorial/connect@2x.png\n\nRequest\n=======\n\nThe Uber API gives you the ability to [Request] an Uber *Product* on behalf of users within your application. Given you know where a user currently is, where they want to go, and which Uber product they want to use to get there, you have all of the tools to make that happen with a few simple API endpoints.\n\n**Note: These endpoints will make requests to active drivers on the Uber platform, directing them to drive to the locations of users who will be charged for all said activity.**\n\nWhile we are giving developers a lot of freedom on how to build interfaces and present information to the users of their applications, there are a few essentials that must be included to ensure a user has all necessary information. This tutorial aims to walk through all of the required Uber API Request calls, how they interact with one another, and provide best practices for building an intuitive user experience.\n\nThe Sandbox\n-----------\n\nBecause of the real-world nature of the Request endpoints, which call active drivers on the system which result in financial transactions on Uber rider accounts, the Uber API provides a Sandbox environment for testing. All Requests made to the API Sandbox will result in a simulated Request that can be programmatically updated.\n\nTo get an understanding on how to set up your development environment setup for making Requests within the sandbox environment, see the [Sandbox Documentation].\n\nThe Basics\n----------\n\nThere are essentially four things the Request endpoints enable your application to do:\n\n- [Make a Request][Request] - POSTing a start lat/lng, end lat/lng, and a `product_id` gets a Request kicked off\n- [Poll Request Status] - once a Request has been created, you can GET that status of that Request, accompanied by other Request details, to keep your user in the loop\n- [Cancel a Request] - Sometimes a user needs to cancel a request and this is done by simpling issuing a DELETE command\n- [Provide a Map] - If you would like to show a visual representation of the Request\n\n [Request]: /docs/v1-requests\n [Sandbox Documentation]: /docs/sandbox\n [Poll Request Status]: /docs/v1-requests-details\n [Cancel a Request]: /docs/v1-requests-cancel\n [Provide a Map]: /docs/v1-requests-map\n\nLife cycle of a Request\n=======================\n\nA Request can go through many states between its start and end. We indicate this state as the status attribute returned by the Request endpoint. The possible values for status are:\n[block:html]\n{\n \"html\": \"<table>\\n<colgroup>\\n<col width=\\\"27%\\\" />\\n<col width=\\\"73%\\\" />\\n</colgroup>\\n<thead>\\n<tr class=\\\"header\\\">\\n<th align=\\\"left\\\">Status</th>\\n<th align=\\\"left\\\">Description</th>\\n</tr>\\n</thead>\\n<tbody>\\n<tr class=\\\"odd\\\">\\n<td align=\\\"left\\\"><code>processing</code></td>\\n<td align=\\\"left\\\">The Request is matching to the most efficient available driver.</td>\\n</tr>\\n<tr class=\\\"even\\\">\\n<td align=\\\"left\\\"><code>no_drivers_available</code></td>\\n<td align=\\\"left\\\">The Request was unfulfilled because no drivers were available.</td>\\n</tr>\\n<tr class=\\\"odd\\\">\\n<td align=\\\"left\\\"><code>accepted</code></td>\\n<td align=\\\"left\\\">The Request has been accepted by a driver and is "en route" to the start location (i.e. <code>start_latitude</code> and <code>start_longitude</code>).</td>\\n</tr>\\n<tr class=\\\"even\\\">\\n<td align=\\\"left\\\"><code>arriving</code></td>\\n<td align=\\\"left\\\">The driver has arrived or will be shortly.</td>\\n</tr>\\n<tr class=\\\"odd\\\">\\n<td align=\\\"left\\\"><code>in_progress</code></td>\\n<td align=\\\"left\\\">The Request is "en route" from the start location to the end location.</td>\\n</tr>\\n<tr class=\\\"even\\\">\\n<td align=\\\"left\\\"><code>driver_canceled</code></td>\\n<td align=\\\"left\\\">The Request has been canceled by the driver.</td>\\n</tr>\\n<tr class=\\\"odd\\\">\\n<td align=\\\"left\\\"><code>rider_canceled</code></td>\\n<td align=\\\"left\\\">The Request canceled by rider.</td>\\n</tr>\\n<tr class=\\\"even\\\">\\n<td align=\\\"left\\\"><code>completed</code></td>\\n<td align=\\\"left\\\">Request has been completed by the driver.</td>\\n</tr>\\n</tbody>\\n</table>\\n\"\n}\n[/block]\n**Overall Request Flow**\n\n![Request Statuses]\n\nAuthorization and Authentication\n================================\n\nApplications that wish to take advantage of the Request endpoints must have their users authorize their application to make requests on their behalf. This is done by having a user grant access of the request scope to your application via OAuth2.0. See the [OAuth 2.0 section of our tutorials] for more details.\n\nOnce a user has effectively authorized your application, all requests to the Reqeust endpoint must be made with an OAuth bearer token.\n\nApplications using the `request` scope must be approved by Uber before they can be made available to the general public. By default, only the developer and invited application admins may make Requests. Access to the `request` scope can be requested in the Authorization tab of your app's settings.\n\nPreparing to make a Request\n===========================\n\nOnce a user has granted your application permission to make Requests on their behalf, you only need three pieces of information to do so:\n\n- **Product** - the product\\_id of the Product the user wishes to have requested.\n- **Start Location** - the latitude and longitude pair of where the user would like to be picked up (usually their current location).\n- **End Location** - the latitude and longitude pair of where the user would like to be dropped off.\n\nThere are typically three items a user wants to know about a Product before choosing one for making a Request:\n\n- **Products Available** - given a location, the Uber Products a user can take advantage of, provided by the [Products] endpoint.\n- **Estimated Time of Arrival** - how quickly a particular product get to your user, provided by the [Time Estimates] endpoint.\n- **Estimated Cost of Service** - how much a user will be charged to go from the start to the end of a Request, provided by the [Price Estimates] endpoint.\n\nOnce you’ve collected the above info, you can present these details to your user to help them select which product is right for them.\n\nTo get the user’s start and end locations, there are quite a few different approaches. Depending on the platform you are developing for, you may get the current location of a user by asking their device at the system level. Perhaps you have a list of recommend locations they can chose. You could also take the same approach as the Uber app and give them a pin on a map that can be dragged and dropped to specify location.\n\n [Request Statuses]: https://d1a3f4spazzrp4.cloudfront.net/developer.uber.com/_static/images/tutorial/request_statuses@2x.png\n [OAuth 2.0 section of our tutorials]: #oauth-2-0\n [approved]: https://developer.uber.com/support#access\n [Products]: /docs/v1-products\n [Time Estimates]: /docs/v1-estimates-time\n [Price Estimates]: /docs/v1-estimates-price\n\nCreating a Request\n==================\n\nNow that you have the product they wish to use and the start and end locations of the Request they would like to make, we have everything we need. Take those values and make a POST on behalf of the user to the [Request] endpoint.\n\n``` sourceCode\ncurl -v -H \"Authorization: Bearer <OAUTH TOKEN>\" \\\n -H \"Content-Type: application/json\" -X POST -d \\ \n '{\"start_latitude\":\"37.334381\",\"start_longitude\":\"-121.89432\",\"end_latitude\":\"37.77703\",\"end_longitude\":\"-122.419571\",\"product_id\":\"a1111c8c-c720-46c3-8534-2fcdd730040d\"}' \\\n https://sandbox-api.uber.com/v1/requests\n```\n\n\nThis POST will result in three possible responses:\n\n- **202 Accepted** - Your Request is successfully being processed\n- **409 Conflict** - An error has occurred, possibly due to [Surge Pricing](https://developer.uber.com/docs/tutorials-rides-api#section-handling-surge-pricing) or no drivers available.\n- **422 Unprocessable Entity** - An error has occurred, most likely due to an issue with the user’s Uber account.\n\nIn most cases, as long as you provide a valid product, start location, and end location, you will get a 202 Accepted response letting you know that the Request was created successfully.\n\n`Status-code 202 Accepted`\n\n``` sourceCode\n{\n \"request_id\":\"852b8fdd-4369-4659-9628-e122662ad257\",\n \"status\":\"processing\",\n \"vehicle\": null,\n \"driver\": null,\n \"location\": null,\n \"eta\": 5,\n}\n```\n\nIn the cases where you receive a `409 Conflict` for surge pricing, please see our [Handling Surge Pricing](https://developer.uber.com/docs/tutorials-rides-api#section-handling-surge-pricing) section of the tutorial.\n\nProcessing a Request\n====================\n\nNow that you have successfully created a Request and have a `request_id` that was returned in the response to your POST, you can continuously poll the Uber API to get the current status and additional details of a Request. We recommend you do this every 3-5 seconds to give the most up-to-date details possible. See Displaying Details of Request for more details.\n\n``` sourceCode\ncurl -v -X \"GET\" \"https://sandbox-api.uber.com/v1/requests/<REQUEST_ID>\" \\\n -H \"Authorization: Bearer <OAUTH TOKEN>\"\n```\n\nDetails you will be provided include the the driver’s name, picture, and phone number as well as the location, make, model and license plate of the vehicle. The more of these details you provide, the better the experience the user will have and the more likely they will successfully complete a Request.\n\n`Status-Code: 200 OK`\n\n``` sourceCode\n{\n \"status\": \"accepted\",\n \"driver\": {\n \"phone_number\": \"(555)555-5555\",\n \"rating\": 5,\n \"picture_url\": \"https:\\/\\/d1w2poirtb3as9.cloudfront.net\\/img.jpeg\",\n \"name\": \"Bob\"\n },\n \"eta\": 4,\n \"location\": {\n \"latitude\": 37.776033,\n \"longitude\": -122.418143,\n \"bearing\": 33\n },\n \"vehicle\": {\n \"make\": \"Bugatti\",\n \"model\": \"Veyron\",\n \"license_plate\": \"I<3Uber\",\n \"picture_url\": \"https:\\/\\/d1w2poirtb3as9.cloudfront.net\\/car.jpeg\",\n },\n \"surge_multiplier\": 1.0,\n \"request_id\": \"b2205127-a334-4df4-b1ba-fc9f28f56c96\"\n}\n```\n\n [Request]: /docs/v1-requests\n [Surge Pricing]: #handling-surge-pricing\n\nCancelling a Request\n====================\n\nIf a user decides to cancel a Request, **you must provide the ability to cancel that Request within your application**.\n\nTo do this, simply send a [DELETE to the Request endpoint] with the specified `request_id` and ensure a successful response is returned. This is usually the result of a user pressing a ‘Cancel’ button and confirming within a modal.\n\n``` sourceCode\ncurl -X \"DELETE\" \"https://sandbox-api.uber.com/v1/requests/<REQUEST_ID>\" \\\n -H \"Authorization: Bearer <OAUTH TOKEN>\"\n```\n\n**Request Initiation and Processing**\n\n![Request Initiation & Processing]\n\n [Request Initiation & Processing]: https://d1a3f4spazzrp4.cloudfront.net/developer.uber.com/_static/images/tutorial/request_initiation_processing@2x.png\n\n\nDisplaying Details of Request\n=============================\n\nAs a Request is ongoing, you will want to display the details of the Request to the user in a way that helps them understand what is happening and give them the information they need to find or get in touch with their driver.\n\nFor instance, when a Request is `processing` it’s probably best to let the user know Uber is attempting to find them a driver. Using a spinner or other loading indicator can convey this message well.\n\nOnce a Request status has changed to `accepted` you can let your user know a vehicle is enroute, what the details of the driver are, and remind them their pickup location. You can even show them the location of the vehicle on a map because the Uber API provides this location information.\n\nIf the Request status becomes `arriving` you probably want to indicate this to the user in a way that gets their attention. And once a Request is `in_progress` you can provide the information a user might find useful once they are already in the vehicle.\n\nUnfortunately, there are some times when a driver must cancel a Request, and your application should let the user know when this happens. This will be indicated when the status of a Request is returned as `driver_canceled.` At this point it’s usually helpful to make it easy for a user to re attempt a Request.\n\nLastly, sometimes a user needs to get in touch with a driver to clarify their location, so please provide an easy way to call or SMS the driver from within your application.\n\n**Request Accepted Flow**\n\n![Request Accepted]\n\n [Request Accepted]: https://d1a3f4spazzrp4.cloudfront.net/developer.uber.com/_static/images/tutorial/request_accepted@2x.png\n\nIndicating Ride Status Throughout Application\n=============================================\n\nOne of the benefits of integrating the Request endpoints within your application is that while a Request is ongoing, you can continue to interact with your user without them leaving your app.\n\nTo take advantage of this, we recommend you present the status of an ongoing Request throughout your application. This provides Request status at a quick glance as well as easy access to more details and Request actions.\n\nThe most common statuses and information users are interested are:\n\n- **Accepted** - The driver is en route, so its a great place to show an ETA\n- **Arriving** - The driver is arriving now! Let your users know its time to find their driver\n- **On Trip** - The user is in a vehicle and off to their destination.\n\n**Indicate Ride Status**\n\n![Indicating Ride Status]\n\n [Indicating Ride Status]: https://d1a3f4spazzrp4.cloudfront.net/developer.uber.com/_static/images/tutorial/request_indicating_ride_status@2x.png\n\nHandling Surge Pricing\n======================\n\nThe way a user accepts surge pricing is similar to how they authorize your application to use the request scope. We provide you with an HREF you send the user to, they accept the the surge multiplier by submitting a web form, and then we redirect back to your application with a surge\\_confirmation\\_id that you use to successfully make a Request.\n\n**Surge Flow**\n\n![Surge Flow]\n\nWhile most of the time making a Request is as easy as providing product and location information, there is a chance that a product with have surge pricing in effect. With surge pricing, Uber rates increase to get more cars on the road and ensure reliability during the busiest times. When enough cars are on the road, prices go back down to normal levels.\n\nTo ensure your users are fully informed about the current pricing of a Product, the Uber API will not allow a Request to be made without the user accepting the current surge price multiple.\n\nTo test this, you need to enable surge pricing by making a PUT to the Products Sandbox endpoint with the desired `surge_multiplier`. Anything above 1.0 will activate surge pricing for a particular Product, which turns on the surge confirmation flow when making a Request for that Product in the Sandbox.\n\nWhen surge pricing is in effect, a POST to create a Request will be returned with a `409 Conflict` error that contains a `surge_confirmation` object within the `meta` component of the response; there are two values present, which are `surge_confirmation_id` and `href.`\n\nFor a user to accept surge pricing, you must send them to the HREF within a web browser. They will be presented with a surge confirmation screen where they must accept the surge multiplier by submitting a web form. In some cases, when the surge multiplier is above a certain limit (most of the time when 2.0x or above), the confirmation page will be a two step process.\n\nOnce a user successfully accepts the surge pricing multiple, they will be redirected to your application via `SURGE_CONFIRMATION_REDIRECT_URI` (that is configurable via the Application Dashboard) which will include the `surge_confirmation_id` as a querystring parameter.\n\nNow that the user has accepted surge and has returned to your application, you may make a second POST to the [Request] endpoint with the `surge_confirmation_id` parameter filled in with the appropriate identifier.\n\n**Note: Because surge pricing fluctuates over time, there is a chance that a surge\\_confirmation\\_id will expire. In this case, the application should retry the the POST request and follow the normal surge flow again.**\n\n [Surge Flow]: https://d1a3f4spazzrp4.cloudfront.net/developer.uber.com/_static/images/tutorial/request_surge@2x.png\n [Request]: /docs/v1-requests\n\nAll Requests Available in Official Uber Apps\n============================================\n\nSince a Request that is made in a 3rd party application is done on behalf of an Uber rider, the status and all details of those Requests will be available within the official Uber apps. This means that if a user chooses to open the Uber app after making a Request with your application, they will have complete functionality as if they made the Request normally.\n\nThis also means that a user can perform the standard actions against a Request within an official Uber app, including canceling. Because of this, your application should always rely on the information provided by the [Request] endpoint to provide the real time status and details of a Request.\n\nNotifications\n=============\n\nAll notifications that a user would receive by Uber, as if they requested using the official Uber app, will be sent for Requests initiated by 3rd party applications. This includes, but is not limited to:\n\n- Push or SMS notifications regarding a Request status\n- Email receipts\n\nBecause Uber is handling notifications to the user about Requests, we recommend only showing in-app notifications about Request status so that a user isn’t bombarded with duplicate messaging. See Indicating Ride Status Throughout Application for some example in-app status indicators.\n\nLimitations\n===========\n\nWhile the current endpoints give you the essentials for requesting trips, there are a few interactions that cannot be completed by the Uber API. These include:\n\n- **Rating drivers** - Requests made and completed cannot be given a rating by a user via the Uber API. All ratings must be done by the Uber app\n- **Displaying receipts** - The fare details of a Request are not provided by the Uber API but all Requests resulting in a charge to a user will produce a receipt emailed to the user’s email address associated with their Uber account\n- **Splitting the fare** - There is no way to initiate a Split Fare request through the Uber API, but users can continue to utilize this feature within the Uber app during the lifecycle of a request\n- **Exclusive products not available** - Uber is continuously creating experimental or promotional products that may not be available to request through the Uber API\n\nGuidelines and Assets\n=====================\n\nTo help you create an application that has an intuitive and familiar user experience, we have provided [design assets, design guidelines, and an overview] of how an entire Request can be implemented within an app.\n\n [Request]: /docs/v1-requests\n [design assets, design guidelines, and an overview]: /docs/design-guidelines","excerpt":"","slug":"tutorials-rides-api","type":"basic","title":"Ride Request"}