A Java library for the Yelp API. It simplifies the process of authentication, request construction, and response parsing for Java/Android developers using the Yelp API. This clientlib requires Java 7 or Android 2.3.
Download the latest JAR or install by using Maven:
<dependency>
<groupId>com.yelp.clientlib</groupId>
<artifactId>yelp-android</artifactId>
<version>1.0.0</version>
</dependency>
or Gradle:
repositories {
mavenCentral()
}
dependencies {
...
compile 'com.yelp.clientlib:yelp-android:1.0.0'
...
}
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(Response<SearchResponse> response, Retrofit retrofit) {
SearchResponse searchResponse = response.body();
// Update UI text with the searchResponse.
}
@Override
public void onFailure(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(Response<Business> response, Retrofit retrofit) {
Business business = response.body();
// Update UI text with the Business object.
}
@Override
public void onFailure(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 gradle 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 gradle integrationTest
. Integration tests will not be ran in the build process
by executing gradle build
.