This projects helps you to make HTTP requests to the Uber Rides API.
Before you begin, you need to register your app in the Uber developer dashboard. Notice that the app gets a client ID, secret, and server token required for authenticating with the API.
After registering your application, you need to install this module in your Node.js project:
npm install node-uber
In order to use this module, you have to import it in your application first:
var Uber = require('node-uber');
Next, initialize the Uber object with the keys you obtained from the Uber developer dashboard:
var uber = new Uber({
client_id: 'CLIENT_ID',
client_secret: 'CLIENT_SECRET',
server_token: 'SERVER_TOKEN',
redirect_uri: 'REDIRECT URL',
name: 'APP_NAME',
language: 'en_US', // optional, defaults to en_US
sandbox: true, // optional, defaults to false
proxy: 'PROXY URL' // optional, defaults to none
});
Note: For all available
language
options check out the Localization page of the API.
To make HTTP calls, you need to create an authenticated session with the API. User-specific operations require you to use a OAuth 2 bearer token with specific scopes. Jump to the method overview section to identify required scopes for methods. General operations can use a simple server-token authentication.
To obtain an OAuth 2 bearer token, you have to authorize your application with the required scope. Available scopes are: history
, history_lite
, profile
, request
, all_trips
, and places
.
To do so, you are initially required to redirect your user to an authorization URL. You can generate the authorization URL using uber.getAuthorizeUrl
. In case you are using Express, your route definition could look as follows:
app.get('/api/login', function(request, response) {
var url = uber.getAuthorizeUrl(['history','profile', 'request', 'places']);
response.redirect(url);
});
The URL will lead to a page where your user will be required to login and approve access to his/her Uber account. In case that step was successful, Uber will issue an HTTP 302 redirect to the redirect_uri defined in the Uber developer dashboard. On that redirect, you will receive an authorization code, which is single use and expires in 10 minutes.
To complete the authorization you now need to receive the callback and convert the given authorization code into an OAuth access token. You can accomplish that using uber.authorizationAsync
. This method will retrieve and store the access_token, refresh_token, authorized scopes, and token expiration date within the uber object for consecutive requests.
Using Express, you could achieve that as follows:
app.get('/api/callback', function(request, response) {
uber.authorizationAsync({authorization_code: request.query.code})
.spread(function(access_token, refresh_token, authorizedScopes, tokenExpiration) {
// store the user id and associated access_token, refresh_token, scopes and token expiration date
console.log('New access_token retrieved: ' + access_token);
console.log('... token allows access to scopes: ' + authorizedScopes);
console.log('... token is valid until: ' + tokenExpiration);
console.log('... after token expiration, re-authorize using refresh_token: ' + refresh_token);
// redirect the user back to your actual app
response.redirect('/web/index.html');
})
.error(function(err) {
console.error(err);
});
});
Nodeback: Looking for nodeback-style methods? Check out the nodeback-readme.
Now that you are authenticated, you can issue requests using provided methods.
For instance, to obtain a list of available Uber products for a specific location, you can use uber.products.getAllForLocationAsync
.
In case you are using Express, your route definition could look as follows:
app.get('/api/products', function(request, response) {
// extract the query from the request URL
var query = url.parse(request.url, true).query;
// if no query params sent, respond with Bad Request
if (!query || !query.lat || !query.lng) {
response.sendStatus(400);
} else {
uber.products.getAllForLocationAsync(query.lat, query.lng)
.then(function(res) {
response.json(res);
})
.error(function(err) {
console.error(err);
response.sendStatus(500);
});
}
});
If your users decide to disconnect or revoke access to their Uber accounts, you can use the uber.revokeTokenAsync
method. This will invalidate either access_token
or refresh_token
. Note that per RFC7009, revoke will return success for any string you pass into the function provided the client_id and client_secret are correct. This includes previously revoked tokens and invalid tokens.
uber.revokeTokenAsync('My_access_token');
Nodeback: Looking for nodeback-style methods? Check out the nodeback-readme.
HTTP Method | Endpoint | Auth Method | Required Scope | Methods |
---|---|---|---|---|
GET | /v1.2/products | OAuth or server_token | products.getAllForAddressAsync | |
GET | /v1.2/products | OAuth or server_token | products.getAllForLocationAsync | |
GET | /v1.2/products/{product_id} | OAuth or server_token | products.getByIDAsync | |
PUT | /v1.2/sandbox/products/{product_id} | OAuth or server_token | (Sandbox mode) | products.setSurgeMultiplierByIDAsync |
PUT | /v1.2/sandbox/products/{product_id} | OAuth or server_token | (Sandbox mode) | products.setDriversAvailabilityByIDAsync |
GET | /v1.2/estimates/price | OAuth or server_token | estimates.getPriceForRouteAsync | |
GET | /v1.2/estimates/price | OAuth or server_token | estimates.getPriceForRouteByAddressAsync | |
GET | /v1.2/estimates/time | OAuth or server_token | estimates.getETAForAddressAsync | |
GET | /v1.2/estimates/time | OAuth or server_token | estimates.getETAForLocationAsync | |
GET | /v1.2/history | OAuth | history or history_lite | user.getHistoryAsync |
GET | /v1.2/me | OAuth | profile | user.getProfileAsync |
PATCH | /v1.2/me | OAuth | profile | user.applyPromoAsync |
POST | /v1.2/requests | OAuth | request (privileged) | requests.createAsync |
GET | /v1.2/requests/current | OAuth | request (privileged) or all_trips (privileged) | requests.getCurrentAsync |
PATCH | /v1.2/requests/current | OAuth | request (privileged) | requests.updateCurrentAsync |
DELETE | /v1.2/requests/current | OAuth | request (privileged) | requests.deleteCurrentAsync |
POST | /v1.2/requests/estimate | OAuth | request (privileged) | requests.getEstimatesAsync |
GET | /v1.2/requests/{request_id} | OAuth | request (privileged) | requests.getByIDAsync |
PATCH | /v1.2/requests/{request_id} | OAuth | request (privileged) | requests.updateByIDAsync |
PUT | /v1.2/sandbox/requests/{request_id} | OAuth | request (privileged & Sandbox mode ) | requests.setStatusByIDAsync |
DELETE | /v1.2/requests/{request_id} | OAuth | request (privileged) | requests.deleteByIDAsync |
GET | /v1.2/requests/{request_id}/map | OAuth | request (privileged) | requests.getMapByIDAsync |
GET | /v1.2/requests/{request_id}/receipt | OAuth | request_receipt (privileged) | requests.getReceiptByIDAsync |
GET | /v1.2/places/{place_id} | OAuth | places | places.getHomeAsync and places.getWorkAsync |
PUT | /v1.2/places/{place_id} | OAuth | places | places.updateHomeAsync and places.updateWorkAsync |
GET | /v1.2/payment-methods | OAuth | request (privileged) | payment.getMethodsAsync |
HTTP Method | Endpoint | Auth Method | Required Scope | Methods |
---|---|---|---|---|
GET | /v1/partners/me | OAuth | partner.accounts | partnerprofile.getProfileAsync |
GET | /v1/partners/payments | OAuth | partner.payments | partnerpayments.getPaymentsAsync |
GET | /v1/partners/trips | OAuth | partner.trips | partnertrips.getTripsAsync |
After getting the authorize url, the user will be redirected to the redirect url with authorization code used in the next function.
uber.getAuthorizeUrl(parameter);
uber.getAuthorizeUrl(['history','profile', 'request', 'places']);
Used to convert authorization code or refresh token into access token.
uber.authorizationAsync(parameter);
authorization_code
OR refresh_token
uber.authorizationAsync({ refresh_token: 'REFRESH_TOKEN' })
.then(function(access_token) { console.log(access_token); })
.error(function(err) { console.error(err); });
});
uber.authorizationAsync({ refresh_token: 'REFRESH_TOKEN' })
.spread(function(access_token, refresh_token, authorizedScopes, tokenExpiration) {
// store the user id and associated access_token, refresh_token, scopes and token expiration date
console.log('New access_token retrieved: ' + access_token);
console.log('... token allows access to scopes: ' + authorizedScopes);
console.log('... token is valid until: ' + tokenExpiration);
console.log('... after token expiration, re-authorize using refresh_token: ' + refresh_token);
})
.error(function(err) { console.error(err); });
});
The product endpoint can be accessed either with an OAuth access_token
or simply with the server_token
because it is not user-specific. It has, therefore, no required scope for access.
This method utilizes geocoder to retrieve the coordinates for an address using Google as the provider. It uses the first element of the response. In other words, the coordinates represent what the Google algorithm provides with most confidence value.
Note: To ensure correct coordinates you should provide the complete address, including city, ZIP code, state, and country.
uber.products.getAllForAddressAsync(address);
uber.products.getAllForAddressAsync('1455 Market St, San Francisco, CA 94103, US')
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
uber.products.getAllForLocationAsync(latitude, longitude);
uber.products.getAllForLocationAsync(3.1357169, 101.6881501)
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
uber.products.getByIDAsync(product_id);
uber.products.getByIDAsync('d4abaae7-f4d6-4152-91cc-77523e8165a4')
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
uber.products.setDriversAvailabilityByIDAsync(product_id, availability);
Note: This method is only allowed in Sandbox mode.
no_drivers_available
error if set to falseuber.products.setDriversAvailabilityByIDAsync('d4abaae7-f4d6-4152-91cc-77523e8165a4', false)
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
uber.products.setSurgeMultiplierByIDAsync(product_id, multiplier);
Note: This method is only allowed in Sandbox mode.
uber.products.setSurgeMultiplierByIDAsync('d4abaae7-f4d6-4152-91cc-77523e8165a4', 2.2)
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
The estimates endpoint can be accessed either with an OAuth access_token
or simply with the server_token
because it is not user-specific. It has, therefore, no required scope for access.
This method utilizes geocoder to retrieve the coordinates for an address using Google as the provider. It uses the first element of the response. In other words, the coordinates represent what the Google algorithm provides with most confidence value.
Note: To ensure correct coordinates you should provide the complete address, including city, ZIP code, state, and country.
uber.estimates.getPriceForRouteByAddressAsync(start_address, end_address, [, seats]);
seats
defaults to 2, which is also the maximum value for this parameter.
uber.estimates.getPriceForRouteByAddressAsync(
'1455 Market St, San Francisco, CA 94103, US',
'2675 Middlefield Rd, Palo Alto, CA 94306, US')
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
uber.estimates.getPriceForRouteAsync(start_latitude, start_longitude, end_latitude, end_longitude [, seats]);
seats
defaults to 2, which is also the maximum value for this parameter.
uber.estimates.getPriceForRouteAsync(3.1357169, 101.6881501, 3.0833, 101.6500)
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
This method utilizes geocoder to retrieve the coordinates for an address using Google as the provider. It uses the first element of the response. In other words, the coordinates represent what the Google algorithm provides with most confidence value.
Note: To ensure correct coordinates you should provide the complete address, including city, ZIP code, state, and country.
uber.estimates.getETAForAddressAsync(address, [, product_id]);
uber.estimates.getETAForAddressAsync('455 Market St, San Francisco, CA 94103, US')
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
});
uber.estimates.getETAForLocationAsync(latitude, longitude [, product_id]);
uber.estimates.getETAForLocationAsync(3.1357169, 101.6881501)
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
The history endpoint can be accessed ONLY with an OAuth access_token
authorized with either the history
or history_lite
(without city information) scope.
uber.user.getHistoryAsync(offset, limit);
offset
defaults to 0 and limit
defaults to 5 with a maximum value of 50.
uber.user.getHistoryAsync(0, 5)
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
The me endpoint can be accessed ONLY with an OAuth access_token
authorized with the profile
scope.
uber.user.getProfileAsync();
uber.user.getProfileAsync()
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
uber.user.applyPromoAsync(code);
uber.user.applyPromoAsync('FREE_RIDEZ')
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
The requests endpoint can be accessed ONLY with an OAuth access_token
authorized with the request
scope.
uber.requests.createAsync(parameter);
start_latitude
& start_longitude
OR start_place_id
end_latitude
& end_longitude
OR end_place_id
fare_id
)startAddress
instead of start_latitude
& start_longitude
and endAddress
instead of end_latitude
& end_longitude
thanks to geocoderNote: To ensure correct coordinates you should provide the complete address, including city, ZIP code, state, and country.
uber.requests.createAsync({
"fare_id": "d30e732b8bba22c9cdc10513ee86380087cb4a6f89e37ad21ba2a39f3a1ba960",
"product_id": "a1111c8c-c720-46c3-8534-2fcdd730040d",
"start_latitude": 37.761492,
"start_longitude": -122.423941,
"end_latitude": 37.775393,
"end_longitude": -122.417546
})
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
Note: By default, only details about trips your app requested will be returned. This endpoint can be used with the scope
all_trips
to get all trips irrespective of which application initiated them.
uber.requests.getCurrentAsync();
uber.requests.getCurrentAsync()
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
uber.requests.updateCurrentAsync(parameter);
startAddress
instead of start_latitude
& start_longitude
and endAddress
instead of end_latitude
& end_longitude
thanks to geocoderNote: To ensure correct coordinates you should provide the complete address, including city, ZIP code, state, and country.
uber.requests.updateCurrentAsync({
"end_latitude": 37.775393,
"end_longitude": -122.417546
})
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
uber.requests.deleteCurrentAsync();
uber.requests.deleteCurrentAsync()
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
uber.requests.getEstimatesAsync(parameter);
start_latitude
& start_longitude
OR start_place_id
end_latitude
& end_longitude
OR end_place_id
startAddress
instead of start_latitude
& start_longitude
and endAddress
instead of end_latitude
& end_longitude
thanks to geocoderNote: To ensure correct coordinates you should provide the complete address, including city, ZIP code, state, and country.
uber.requests.getEstimatesAsync({
"product_id": "a1111c8c-c720-46c3-8534-2fcdd730040d",
"start_latitude": 37.761492,
"start_longitude": -122.423941,
"end_latitude": 37.775393,
"end_longitude": -122.417546
})
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
uber.requests.getByIDAsync(request_id);
uber.requests.getByIDAsync('17cb78a7-b672-4d34-a288-a6c6e44d5315')
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
uber.requests.updateByIDAsync(request_id, parameter);
startAddress
instead of start_latitude
& start_longitude
and endAddress
instead of end_latitude
& end_longitude
thanks to geocoderNote: To ensure correct coordinates you should provide the complete address, including city, ZIP code, state, and country.
uber.requests.updateByIDAsync('17cb78a7-b672-4d34-a288-a6c6e44d5315', {
"end_latitude": 37.775393,
"end_longitude": -122.417546
})
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
uber.requests.setStatusByIDAsync(request_id, status);
Note: This method is only allowed in Sandbox mode. Check out the documentation for valid status properties.
uber.requests.setStatusByIDAsync('17cb78a7-b672-4d34-a288-a6c6e44d5315', 'accepted')
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
uber.requests.deleteByIDAsync(request_id);
uber.requests.deleteByIDAsync('17cb78a7-b672-4d34-a288-a6c6e44d5315')
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
uber.requests.getMapByIDAsync(request_id);
Unless the referenced request is in status accepted
, a 404 error will be returned.
uber.requests.getMapByIDAsync('17cb78a7-b672-4d34-a288-a6c6e44d5315')
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
Note: This endpoint requires OAuth authentication with the scope
request_receipt
uber.requests.getReceiptByIDAsync(request_id);
The referenced request must be in status completed
.
uber.requests.getReceiptByIDAsync('17cb78a7-b672-4d34-a288-a6c6e44d5315')
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
The places endpoint can be accessed ONLY with an OAuth access_token
authorized with the places
scope.
Note: As of right now, only two place_ids are allowed:
home
andwork
.
uber.places.getHomeAsync();
uber.places.getHomeAsync()
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
uber.places.getWorkAsync();
uber.places.getWorkAsync()
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
uber.places.updateHomeAsync(address);
uber.places.updateHomeAsync('685 Market St, San Francisco, CA 94103, USA')
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
uber.places.updateWorkAsync(address);
uber.places.updateWorkAsync('1455 Market St, San Francisco, CA 94103, USA')
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
The payment-methods endpoint can be accessed ONLY with an OAuth access_token
authorized with the request
scope.
uber.payment.getMethodsAsync();
uber.payment.getMethodsAsync()
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
The partners endpoints (Driver API) can be accessed ONLY with an OAuth access_token
authorized with the respective scopes (partner.accounts
, partner.trips
, or partner.payments
).
uber.partnerprofile.getProfileAsync();
uber.partnerprofile.getProfileAsync()
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
uber.partnerpayments.getPaymentsAsync(offset, limit, from_time, to_time);
0
5
uber.partnerpayments.getPaymentsAsync(0, 50, 1451606400, 1505160819)
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
uber.partnertrips.getTripsAsync(offset, limit, from_time, to_time);
0
5
uber.partnertrips.getTripsAsync(0, 50, 1451606400, 1505160819)
.then(function(res) { console.log(res); })
.error(function(err) { console.error(err); });
You can execute all existing tests using script test/allTests.js
. These tests include linting, code coverage, and unit tests.
npm test
In case you would like to contribute to this project, please ensure that all the tests pass before you create a PR. We have strict code style and code coverage (>= 95%) requirements.
The change-log can be found in the Wiki: Version History.