An Android library for the Yelp API v2. It simplifies the process of authentication, request construction, and response parsing for Android developers using the Yelp API v2. This clientlib has been tested with applications written in Android API level 15 and 25.
Download the latest AAR or install by using Maven:
<dependency>
<groupId>com.yelp.clientlib</groupId>
<artifactId>yelp-android</artifactId>
<version>3.0.0</version>
</dependency>
or Gradle:
repositories {
mavenCentral()
}
dependencies {
...
compile 'com.yelp.clientlib:yelp-android:3.0.0'
...
}
Proguard rules for the library can be found here
This library uses a YelpAPI
object to query against the API. Instantiate a YelpAPI
object by using
YelpAPIFactory
with your API keys.
YelpAPIFactory apiFactory = new YelpAPIFactory(consumerKey, consumerSecret, token, tokenSecret);
YelpAPI yelpAPI = apiFactory.createAPI();
Once you have a YelpAPI
object you can use the search
function to generate a Call
object which makes a request to
the Search API.
The general params and locale options should be passed to the method as a Map<String, String>
. The full list of
parameters can be found in the Search API Documentation.
Map<String, String> params = new HashMap<>();
// general params
params.put("term", "food");
params.put("limit", "3");
// locale params
params.put("lang", "fr");
Call<SearchResponse> call = yelpAPI.search("San Francisco", params);
Now you can execute the Call
object to send the request.
Response<SearchResponse> response = call.execute();
You can also pass in a Callback
object to send the request asynchronously. For more see Asynchronous Requests section.
Callback<SearchResponse> callback = new Callback<SearchResponse>() {
@Override
public void onResponse(Call<SearchResponse> call, Response<SearchResponse> response) {
SearchResponse searchResponse = response.body();
// Update UI text with the searchResponse.
}
@Override
public void onFailure(Call<SearchResponse> call, Throwable t) {
// HTTP error happened, do something to handle it.
}
};
call.enqueue(callback);
Additionally there are two more search methods for searching by a bounding box or for geographical coordinates:
// bounding box
BoundingBoxOptions bounds = BoundingBoxOptions.builder()
.swLatitude(37.7577)
.swLongitude(-122.4376)
.neLatitude(37.785381)
.neLongitude(-122.391681).build();
Call<SearchResponse> call = yelpAPI.search(bounds, params);
Response<SearchResponse> response = call.execute();
// coordinates
CoordinateOptions coordinate = CoordinateOptions.builder()
.latitude(37.7577)
.longitude(-122.4376).build();
Call<SearchResponse> call = yelpAPI.search(coordinate, params);
Response<SearchResponse> response = call.execute();
To query the Business API, use the getBusiness
function with a business_id
. You can also pass in locale parameters
in a Map<String, String>
as specified in the Business API Documentation.
Call<Business> call = yelpAPI.getBusiness("yelp-san-francisco");
Response<Business> response = call.execute();
You can pass in locale information as well.
Map<String, String> params = new HashMap<>();
params.put("lang", "fr");
Call<Business> call = yelpAPI.getBusiness("yelp-san-francisco", params);
Response<Business> response = call.execute();
To query the Phone Search API, use the getPhoneSearch
function with a phone number. Additional parameters can be
passed in by using a Map<String, String>
as specified in the Phone Search API Documentation.
Call<SearchResponse> call = yelpAPI.getPhoneSearch("+15555555555");
Response<SearchResponse> response = call.execute();
You can pass in country code information as well
Map<String, String> params = new HashMap<>();
params.put("cc", "US");
params.put("category", "fashion");
Call<SearchResponse> call = yelpAPI.getPhoneSearch("5555555555", params);
Response<SearchResponse> response = call.execute();
This library uses Retrofit as the HTTP client. To send a request asynchronously,
use Call.enqueue()
to set Callback
function for an asynchronous request.
Callback<Business> callback = new Callback<Business>() {
@Override
public void onResponse(Call<Business> call, Response<Business> response) {
Business business = response.body();
// Update UI text with the Business object.
}
@Override
public void onFailure(Call<Business> call, Throwable t) {
// HTTP error happened, do something to handle it.
}
};
Call<Business> call = yelpAPI.getBusiness(businessId);
call.enqueue(callback);
You can cancel asynchronous requests by simply call cancel()
on Call
objects. It is important to cancel your calls
while your Activity
is being destroyed to avoid memory leaks.
Call<Business> call = yelpAPI.getBusiness(businessId);
call.enqueue(callback);
// Activity is being destroyed and the call should be canceled.
call.cancel();
For more information about the usage of asynchronous requests in Retrofit, see Retrofit documentation.
After Call
object is executed, a Response
contains parsed Java objects will be returned, use Response.body()
to
get parsed Java objects.
Search and phone search responses are parsed into SearchResponse
objects.
Call<SearchResponse> call = yelpAPI.search("San Francisco", params);
SearchResponse searchResponse = call.execute().body();
int totalNumberOfResult = searchResponse.total(); // 3
ArrayList<Business> businesses = searchResponse.businesses();
String businessName = businesses.get(0).name(); // "JapaCurry Truck"
Double rating = businesses.get(0).rating(); // 4.0
Business responses are parsed into Business
objects directly.
Call<Business> call = yelpAPI.business("japacurry-truck-san-francisco");
Response<Business> response = call.execute();
Business business = response.body();
String businessName = business.name(); // "JapaCurry Truck"
Double rating = business.rating(); // 4.0
For a full list of available response fields, take a look at the documentation or the classes defined in com.yelp.clientlib.entities.
- Fork it (http://github.com/yelp/yelp-android/fork)
- Create your feature branch (git checkout -b my-new-feature)
- Commit your changes (git commit -am 'Add some feature')
- Push to the branch (git push origin my-new-feature)
- Create new Pull Request
Please write tests for any new features. We use JUnit + Gradle so just run ./gradlew test
to run the full test suite.
To know more about running JUnit tests in Gradle, see [Gradle: The Java Plugin - Test](https://docs.gradle
.org/current/userguide/java_plugin.html#sec:java_test).
If you are adding a new integration test, you will need to connect to the Yelp API. You can set this up by putting
your API keys into src/integration-test/resources/credentials.yaml
in the following format:
consumer_key: YOUR_CONSUMER_KEY
consumer_secret: YOUR_CONSUMER_SECRET
token: YOUR_TOKEN
token_secret: YOUR_TOKEN_SECRET
To run the integration tests, execute ./gradlew integrationTest
. Integration tests will not be ran in the build
process by executing ./gradlew build
.