fi.foyt.foursquare.api

Class FoursquareApi

java.lang.Object

fi.foyt.foursquare.api.FoursquareApi

public class FoursquareApi
extends Object

Entry point for FoursquareAPI.

See Also:

https://developer.foursquare.com/docs/index_docs.html

Constructor Summary

Constructors

Constructor and Description
FoursquareApi(String clientId, String clientSecret, String redirectUrl) Constructor.
FoursquareApi(String clientId, String clientSecret, String redirectUrl, IOHandler ioHandler) Constructor.
FoursquareApi(String clientId, String clientSecret, String redirectUrl, String oAuthToken, IOHandler ioHandler) Constructor.

Method Summary

Methods

Modifier and Type	Method and Description
void	authenticateCode(String code) Exchanges code for oAuthToken
Result<Checkin>	checkin(String checkinId, String signature) Get details of a checkin.
Result<Checkin>	checkinsAdd(String venueId, String venue, String shout, String broadcast, String ll, Double llAcc, Double alt, Double altAcc) Allows you to check in to a place.
Result<Comment>	checkinsAddComment(String checkinId, String text) Comment on a checkin-in
Result<Checkin>	checkinsDeleteComment(String checkinId, String commentId) Remove a comment from a checkin, if the acting user is the author or the owner of the checkin.
Result<Checkin[]>	checkinsRecent(String ll, Integer limit, Long afterTimestamp) Returns a list of recent checkins from friends.
String	getAuthenticationUrl() Returns user authentication URL
IOHandler	getIOHandler() Returns current IOHandler
String	getOAuthToken() Returns OAuthToken
boolean	getUseCallback() Returns if JSON request mode is callback
Result<Photo>	photo(String id) Get details of a photo.
Result<Photo>	photosAdd(String checkinId, String tipId, String venueId, String broadcast, String ll, Double llAcc, Double alt, Double altAcc, byte[] data) Allows user to add a new photo to a checkin, tip, or a venue in general.
void	setoAuthToken(String oAuthToken) Sets OAuthToken
void	setSkipNonExistingFields(boolean skipNonExistingFields) Sets debugging flag what ever parser should disregard non-existing fields
Result<Setting>	settingsAll() Returns the settings of the acting user.
Result<Setting>	settingSet(String settingId, Boolean value) Change a setting for the given user.
void	setUseCallback(boolean useCallback) Change JSON request mode to callback or normal
void	setVersion(String version) Sets Foursquare API version
Result<CompleteSpecial>	special(String id, String venueId) Gives details about a special, including text and whether it is unlocked for the current user.
Result<SpecialGroup>	specialsSearch(String ll, Double llAcc, Double alt, Double altAcc, Integer limit) Returns a list of specials near the current location.
Result<CompleteTip>	tip(String id) Gives details about a tip, including which users (especially friends) have marked the tip to-do or done.
Result<CompleteTip>	tipsAdd(String venueId, String text, String url) Allows user to add a new tip at a venue.
Result<CompleteTip>	tipsMarkDone(String tipId) Allows the acting user to mark a tip done.
Result<Todo>	tipsMarkTodo(String tipId) Allows you to mark a tip to-do.
Result<CompleteTip[]>	tipsSearch(String ll, Integer limit, Integer offset, String filter, String query) Returns a list of tips near the area specified.
Result<CompleteTip>	tipsUnmark(String tipId) Allows user to remove a tip from your to-do list or done list.
Result<CompleteUser>	user(String userId) Returns profile information for a given user, including selected badges and mayorships.
Result<CompleteUser>	usersApprove(String userId) Approves a pending friend request from another user.
Result<Badges>	usersBadges(String userId) Returns badges for a given user.
Result<CheckinGroup>	usersCheckins(String userId, Integer limit, Integer offset, Long afterTimestamp, Long beforeTimestamp) Returns a history of checkins for the authenticated user.
Result<CompleteUser>	usersDeny(String userId) Denies a pending friend request
Result<UserGroup>	usersFriends(String userId) Returns user's friends.
Result<LeaderboardItemGroup>	usersLeaderboard(Integer neighbors) Returns the user's leaderboard.
Result<CompleteUser>	usersRequest(String id) Sends a friend request to another user.
Result<CompactUser[]>	usersRequests() Returns a list of users with whom they have a pending friend requests.
Result<CompactUser[]>	usersSearch(String phone, String email, String twitter, String twitterSource, String fbid, String name) Find users
Result<CompleteUser>	usersSetPings(String userId, String value) Changes whether the acting user will receive pings (phone notifications) when the specified user checks in.
Result<TipGroup>	usersTips(String userId, String sort, String ll, Integer limit, Integer offset) Returns tips from a user.
Result<TodoGroup>	usersTodos(String userId, String sort, String ll) Returns todos from a user.
Result<CompleteUser>	usersUnfriend(String userId) Cancels any relationship between the acting user and the specified user.
Result<VenueHistoryGroup>	usersVenueHistory(String userId, Long beforeTimestamp, Long afterTimestamp) Returns a list of all venues visited by the specified user, along with how many visits and when they were last there.
Result<CompleteVenue>	venue(String venueId) Gives details about a venue, including location, mayorship, tags, tips, specials, and category.
Result<CompleteVenue>	venuesAdd(String name, String address, String crossStreet, String city, String state, String zip, String phone, String ll, String primaryCategoryId) Allows user to add a new venue.
Result<Category[]>	venuesCategories() Returns a hierarchical list of categories applied to venues.
Result<Object>	venuesEdit(String id, String name, String address, String crossStreet, String city, String state, String zip, String phone, String ll, String categoryId, String twitter, String description, String url) Allows you to make changes to a venue (acting user must be a superuser or venue manager).
Result<Recommended>	venuesExplore(String ll, Double llAcc, Double alt, Double altAcc, Integer radius, String section, String query, Integer limit, String basis) Returns a list of recommended venues near the specified location.
Result<Object>	venuesFlag(String id, String problem, String venueId) Allows users to indicate a venue is incorrect in some way.
Result<CheckinGroup>	venuesHereNow(String venueId, Integer limit, Integer offset, Long afterTimestamp) Provides a count of how many people are at a given venue.
Result<LinkGroup>	venuesLinks(String id) Returns URLs or identifiers from third parties that have been applied to this venue
Result<Todo>	venuesMarkTodo(String venuesId, String text) Allows you to mark a venue to-do, with optional text.
Result<PhotoGroup>	venuesPhotos(String venueId, String group, Integer limit, Integer offset) Returns photos for a venue.
Result<Object>	venuesProposeEdit(String id, String name, String address, String crossStreet, String city, String state, String zip, String phone, String ll, String primaryCategoryId) Allows user to propose a change to a venue.
Result<VenuesSearchResult>	venuesSearch(Map<String,String> params) Generic search which takes a map of parameters The map is converted into parameters for the search API call with key/value pairs matching https://developer.foursquare.com/docs/venues/search For example: public Response foursquareSearchNamed(@QueryParam("place") String place, @QueryParam("term") String searchTerm) { Map searchParams = new HashMap(); FoursquareApi foursquareApi = new FoursquareApi(, , ); searchParams.put("near", place); searchParams.put("query", searchTerm); searchParams.put("limit","50"); try { Result result = foursquareApi.venuesSearch(searchParams); if(result != null) { return Response.ok(result.getResult()).build(); } } catch (Exception e) { e.printStackTrace(); log.warning("Problem with foursquare search"); } return Response.noContent().build(); }
Result<VenuesSearchResult>	venuesSearch(String ll, Double llAcc, Double alt, Double altAcc, String query, Integer limit, String intent, String categoryId, String url, String providerId, String linkedId, Integer radius, String near) Returns a list of venues near the current location, optionally matching the search term.
Result<VenuesSearchResult>	venuesSearch(String near, String query, Integer limit, String intent, String categoryId, String url, String providerId, String linkedId) Returns a list of venues near the current location identified by place (i.e.
Result<VenuesAutocompleteResult>	venuesSuggestCompletion(String ll, Double llAcc, Double alt, Double altAcc, String query, int limit) Venues Autocomplete https://developer.foursquare.com/docs/venues/suggestcompletion
Result<TipGroup>	venuesTips(String venueId, String sort, Integer limit, Integer offset) Returns tips for a venue.
Result<CompactVenue[]>	venuesTrending(String ll, Integer limit, Integer radius) Returns a list of venues near the current location with the most people currently checked in.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FoursquareApi

public FoursquareApi(String clientId,
             String clientSecret,
             String redirectUrl)

Constructor.

Parameters:

clientId - Foursquare Client id

clientSecret - Foursquare Client secret

redirectUrl - Foursquare Redirect URL

FoursquareApi

public FoursquareApi(String clientId,
             String clientSecret,
             String redirectUrl,
             IOHandler ioHandler)

Constructor.

Parameters:

clientId - Foursquare Client id

clientSecret - Foursquare Client secret

redirectUrl - Foursquare Redirect URL

ioHandler - IOHandler

FoursquareApi

public FoursquareApi(String clientId,
             String clientSecret,
             String redirectUrl,
             String oAuthToken,
             IOHandler ioHandler)

Constructor.

Parameters:

clientId - Foursquare Client id

clientSecret - Foursquare Client secret

redirectUrl - Foursquare Redirect URL

oAuthToken - Previously retrieved OAuthToken

ioHandler - IOHandler

Method Detail

getOAuthToken

public String getOAuthToken()

Returns OAuthToken

Returns:

OAuthToken

setoAuthToken

public void setoAuthToken(String oAuthToken)

Sets OAuthToken

Parameters:

oAuthToken - OAuthToken

setSkipNonExistingFields

public void setSkipNonExistingFields(boolean skipNonExistingFields)

Sets debugging flag what ever parser should disregard non-existing fields

Parameters:

skipNonExistingFields - debugging flag what ever parser should disregard non-existing fields

setVersion

public void setVersion(String version)

Sets Foursquare API version

Parameters:

version - Foursquare API version

setUseCallback

public void setUseCallback(boolean useCallback)

Change JSON request mode to callback or normal

Parameters:

useCallback - set false to enable normal mode

getUseCallback

public boolean getUseCallback()

Returns if JSON request mode is callback

Returns:

if JSON request mode is callback

user

public Result<CompleteUser> user(String userId)
                          throws FoursquareApiException

Returns profile information for a given user, including selected badges and mayorships.

Parameters:

userId - User id (can be 'self' in case of the current user, assumed 'self' if null)

Returns:

CompleteUser entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/users/users.html

usersLeaderboard

public Result<LeaderboardItemGroup> usersLeaderboard(Integer neighbors)
                                              throws FoursquareApiException

Returns the user's leaderboard.

Parameters:

neighbors - number of friends' scores to return that are adjacent to user's score

Returns:

LeaderboardItemGroup entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/users/leaderboard.html

usersBadges

public Result<Badges> usersBadges(String userId)
                           throws FoursquareApiException

Returns badges for a given user.

Parameters:

userId - User id (can be 'self' in case of the current user, assumed 'self' if null)

Returns:

Badges entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/users/badges.html

usersCheckins

public Result<CheckinGroup> usersCheckins(String userId,
                                 Integer limit,
                                 Integer offset,
                                 Long afterTimestamp,
                                 Long beforeTimestamp)
                                   throws FoursquareApiException

Returns a history of checkins for the authenticated user.

Parameters:

userId - User id (For now, only 'self' is supported, 'self' assumed if null)

limit - number of results to return

offset - used to page through results.

afterTimestamp - retrieve the first results to follow these seconds since epoch.

beforeTimestamp - retrieve the first results prior to these seconds since epoch.

Returns:

CheckinGroup entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/users/checkins.html

usersTips

public Result<TipGroup> usersTips(String userId,
                         String sort,
                         String ll,
                         Integer limit,
                         Integer offset)
                           throws FoursquareApiException

Returns tips from a user.

Parameters:

userId - User id (can be 'self' in case of the current user, assumed 'self' if null)

sort - one of recent, nearby, or popular. Nearby requires ll to be provided.

ll - latitude and longitude of the user's location.

limit - number of results to return, up to 500.

offset - used to page through results.

Returns:

TipGroup entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/users/tips.html

usersTodos

public Result<TodoGroup> usersTodos(String userId,
                           String sort,
                           String ll)
                             throws FoursquareApiException

Returns todos from a user.

Parameters:

userId - User id (can be 'self' in case of the current user, assumed 'self' if null)

sort - one of recent or popular. Nearby requires ll to be provided.

ll - latitude and longitude of the user's location

Returns:

TodoGroup entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/users/todos.html

usersVenueHistory

public Result<VenueHistoryGroup> usersVenueHistory(String userId,
                                          Long beforeTimestamp,
                                          Long afterTimestamp)
                                            throws FoursquareApiException

Returns a list of all venues visited by the specified user, along with how many visits and when they were last there.

Parameters:

userId - User id (For now, only 'self' is supported, 'self' assumed if null)

beforeTimestamp - seconds since epoch.

afterTimestamp - seconds after epoch.

Returns:

VenueHistoryGroup entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/users/venuehistory.html

usersRequest

public Result<CompleteUser> usersRequest(String id)
                                  throws FoursquareApiException

Sends a friend request to another user.

Parameters:

id - user id to which a request will be sent.

Returns:

CompleteUser entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/users/request.html

usersUnfriend

public Result<CompleteUser> usersUnfriend(String userId)
                                   throws FoursquareApiException

Cancels any relationship between the acting user and the specified user.

Parameters:

userId - user id of the user to be unfriended.

Returns:

CompleteUser entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/users/unfriend.html

usersApprove

public Result<CompleteUser> usersApprove(String userId)
                                  throws FoursquareApiException

Approves a pending friend request from another user.

Parameters:

userId - the user id of a pending friend.

Returns:

CompleteUser entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/users/approve.html

usersDeny

public Result<CompleteUser> usersDeny(String userId)
                               throws FoursquareApiException

Denies a pending friend request

Parameters:

userId - the user id of a pending friend.

Returns:

CompleteUser entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/users/deny.html

usersSetPings

public Result<CompleteUser> usersSetPings(String userId,
                                 String value)
                                   throws FoursquareApiException

Changes whether the acting user will receive pings (phone notifications) when the specified user checks in.

Parameters:

userId - the user id of a friend.

value - true or false.

Returns:

CompleteUser entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/users/setpings.html

usersSearch

public Result<CompactUser[]> usersSearch(String phone,
                                String email,
                                String twitter,
                                String twitterSource,
                                String fbid,
                                String name)
                                  throws FoursquareApiException

Find users

Parameters:

phone - a comma-delimited list of phone numbers to look for.

email - a comma-delimited list of email addresses to look for.

twitter - a comma-delimited list of Twitter handles to look for.

twitterSource - a single Twitter handle. Results will be friends of this user who use Foursquare.

fbid - a comma-delimited list of Facebook id's to look for.

name - a single string to search for in users' names.

Returns:

array of CompactUser entities wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/users/search.html

usersRequests

public Result<CompactUser[]> usersRequests()
                                    throws FoursquareApiException

Returns a list of users with whom they have a pending friend requests.

Returns:

array of CompactUser entities wrapped in a Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/users/requests.html

usersFriends

public Result<UserGroup> usersFriends(String userId)
                               throws FoursquareApiException

Returns user's friends.

Parameters:

userId - User id (can be 'self' in case of the current user, assumed 'self' if null)

Returns:

UserGroup entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/users/friends.html

venue

public Result<CompleteVenue> venue(String venueId)
                            throws FoursquareApiException

Gives details about a venue, including location, mayorship, tags, tips, specials, and category.

Parameters:

venueId - id of venue to retrieve

Returns:

CompleteVenue entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/venues/venues.html

venuesExplore

public Result<Recommended> venuesExplore(String ll,
                                Double llAcc,
                                Double alt,
                                Double altAcc,
                                Integer radius,
                                String section,
                                String query,
                                Integer limit,
                                String basis)
                                  throws FoursquareApiException

Returns a list of recommended venues near the specified location.

Parameters:

ll - latitude and longitude of the location in question, so response can include distance.

llAcc - accuracy of latitude and longitude, in meters.

alt - altitude of the user's location, in meters.

altAcc - accuracy of the user's altitude, in meters.

radius - radius to search within, in meters.

section - one of food, drinks, coffee, shops, or arts. Choosing one of these limits results to venues with categories matching these terms.

query - a search term to be applied against tips, category, tips, etc. at a venue.

limit - number of results to return, up to 50.

basis - if present and set to friends or me, limits results to only places where friends have visited or user has visited, respectively.

Returns:

Recommended entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/venues/explore.html

venuesHereNow

public Result<CheckinGroup> venuesHereNow(String venueId,
                                 Integer limit,
                                 Integer offset,
                                 Long afterTimestamp)
                                   throws FoursquareApiException

Provides a count of how many people are at a given venue. If the request is user authenticated, also returns a list of the users there, friends-first.

Parameters:

venueId - id of venue to retrieve

limit - number of results to return, up to 500.

offset - used to page through results.

afterTimestamp - retrieve the first results to follow these seconds since epoch

Returns:

CheckinGroup entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/venues/herenow.html

venuesTips

public Result<TipGroup> venuesTips(String venueId,
                          String sort,
                          Integer limit,
                          Integer offset)
                            throws FoursquareApiException

Returns tips for a venue.

Parameters:

venueId - id of venue

sort - one of recent or popular

limit - number of results to return, up to 500.

offset - used to page through results.

Returns:

TipGroup entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/venues/tips.html

venuesPhotos

public Result<PhotoGroup> venuesPhotos(String venueId,
                              String group,
                              Integer limit,
                              Integer offset)
                                throws FoursquareApiException

Returns photos for a venue.

Parameters:

venueId - the venue you want photos for.

group - pass checkin for photos added by friends on their recent checkins. Pass venue for public photos added to the venue by anyone. Use multi to fetch both.

limit - number of results to return, up to 500.

offset - used to page through results.

Returns:

PhotoGroup entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/venues/photos.html

venuesLinks

public Result<LinkGroup> venuesLinks(String id)
                              throws FoursquareApiException

Returns URLs or identifiers from third parties that have been applied to this venue

Parameters:

id - id of the venue

Returns:

LinkGroup entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/venues/links.html

venuesMarkTodo

public Result<Todo> venuesMarkTodo(String venuesId,
                          String text)
                            throws FoursquareApiException

Allows you to mark a venue to-do, with optional text.

Parameters:

venuesId - the venue id

text - The text of the tip.

Returns:

Todo entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/venues/marktodo.html

venuesFlag

public Result<Object> venuesFlag(String id,
                        String problem,
                        String venueId)
                          throws FoursquareApiException

Allows users to indicate a venue is incorrect in some way.

Parameters:

id - the venue id for which an edit is being proposed.

problem - one of mislocated, closed, duplicate.

venueId - of a duplicate, only valid for problem = duplicate

Returns:

Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/venues/flag.html

venuesProposeEdit

public Result<Object> venuesProposeEdit(String id,
                               String name,
                               String address,
                               String crossStreet,
                               String city,
                               String state,
                               String zip,
                               String phone,
                               String ll,
                               String primaryCategoryId)
                                 throws FoursquareApiException

Allows user to propose a change to a venue.

Parameters:

id - the venue id for which an edit is being proposed.

name - the name of the venue.

address - the address of the venue.

crossStreet - the nearest intersecting street or streets.

city - the city name where this venue is.

state - the nearest state or province to the venue.

zip - the nearest state or province to the venue.

phone - the phone number of the venue.

ll - latitude and longitude of the user's location, as accurate as is known.

primaryCategoryId - the ID of the category to which you want to assign this venue.

Returns:

Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/venues/proposeedit.html

venuesEdit

public Result<Object> venuesEdit(String id,
                        String name,
                        String address,
                        String crossStreet,
                        String city,
                        String state,
                        String zip,
                        String phone,
                        String ll,
                        String categoryId,
                        String twitter,
                        String description,
                        String url)
                          throws FoursquareApiException

Allows you to make changes to a venue (acting user must be a superuser or venue manager). Any blank parameter deletes an old value, any unspecified parameter does nothing.

Parameters:

id - the venue id for which an edit is being proposed.

name - the name of the venue.

address - the address of the venue.

crossStreet - the nearest intersecting street or streets.

city - the city name where this venue is.

state - the nearest state or province to the venue.

zip - the nearest state or province to the venue.

phone - the phone number of the venue.

ll - latitude and longitude of the user's location, as accurate as is known.

categoryId - the ID of the category to which you want to assign this venue.

twitter - The twitter handle of the venue.

description - A freeform description of the venue, up to 300 characters.

url - The url of the homepage of the venue.

Returns:

Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/venues/edit.html

venuesAdd

public Result<CompleteVenue> venuesAdd(String name,
                              String address,
                              String crossStreet,
                              String city,
                              String state,
                              String zip,
                              String phone,
                              String ll,
                              String primaryCategoryId)
                                throws FoursquareApiException

Allows user to add a new venue.

Parameters:

name - the name of the venue

address - the address of the venue.

crossStreet - the nearest intersecting street or streets.

city - the city name where this venue is.

state - the nearest state or province to the venue.

zip - the zip or postal code for the venue.

phone - the phone number of the venue.

ll - latitude and longitude of the venue, as accurate as is known.

primaryCategoryId - the ID of the category to which you want to assign this venue.

Returns:

CompleteVenue entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/venues/add.html

venuesCategories

public Result<Category[]> venuesCategories()
                                    throws FoursquareApiException

Returns a hierarchical list of categories applied to venues.

Returns:

Array of Category entities wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/venues/categories.html

venuesSearch

public Result<VenuesSearchResult> venuesSearch(String ll,
                                      Double llAcc,
                                      Double alt,
                                      Double altAcc,
                                      String query,
                                      Integer limit,
                                      String intent,
                                      String categoryId,
                                      String url,
                                      String providerId,
                                      String linkedId,
                                      Integer radius,
                                      String near)
                                        throws FoursquareApiException

Returns a list of venues near the current location, optionally matching the search term.

Parameters:

ll - latitude and longitude of the user's location. (Required for query searches)

llAcc - accuracy of latitude and longitude, in meters. (Does not currently affect search results.)

alt - altitude of the user's location, in meters. (Does not currently affect search results.)

altAcc - accuracy of the user's altitude, in meters. (Does not currently affect search results.)

query - a search term to be applied against titles.

limit - number of results to return, up to 50.

intent - one of checkin, match or specials

categoryId - a category to limit results to

url - a third-party URL

providerId - identifier for a known third party

linkedId - identifier used by third party specifed in providerId parameter

radius - Limit results to venues within this many meters of the specified location. Maximum is 100 000 meters.

near - Required if ll is not provided. A string naming a place in the world. Will be geocodd. (required for query searches)

Returns:

VenuesSearchResult object wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/venues/search.html

venuesSearch

public Result<VenuesSearchResult> venuesSearch(Map<String,String> params)
                                        throws FoursquareApiException

Generic search which takes a map of parameters The map is converted into parameters for the search API call with key/value pairs matching https://developer.foursquare.com/docs/venues/search For example: public Response foursquareSearchNamed(@QueryParam("place") String place, @QueryParam("term") String searchTerm) { Map searchParams = new HashMap(); FoursquareApi foursquareApi = new FoursquareApi(, , ); searchParams.put("near", place); searchParams.put("query", searchTerm); searchParams.put("limit","50"); try { Result result = foursquareApi.venuesSearch(searchParams); if(result != null) { return Response.ok(result.getResult()).build(); } } catch (Exception e) { e.printStackTrace(); log.warning("Problem with foursquare search"); } return Response.noContent().build(); }

Throws:

FoursquareApiException

venuesSearch

public Result<VenuesSearchResult> venuesSearch(String near,
                                      String query,
                                      Integer limit,
                                      String intent,
                                      String categoryId,
                                      String url,
                                      String providerId,
                                      String linkedId)
                                        throws FoursquareApiException

Returns a list of venues near the current location identified by place (i.e. Chicago, IL, optionally matching the search term.

Parameters:

near - the name of a city or town which can be geocoded by foursquare

query - a search term to be applied against titles.

limit - number of results to return, up to 50.

intent - one of checkin, match or specials

categoryId - a category to limit results to

url - a third-party URL

providerId - identifier for a known third party

linkedId - identifier used by third party specifed in providerId parameter

Returns:

VenuesSearchResult object wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/venues/search.html

venuesSuggestCompletion

public Result<VenuesAutocompleteResult> venuesSuggestCompletion(String ll,
                                                       Double llAcc,
                                                       Double alt,
                                                       Double altAcc,
                                                       String query,
                                                       int limit)
                                                         throws FoursquareApiException

Venues Autocomplete https://developer.foursquare.com/docs/venues/suggestcompletion

Parameters:

ll -

llAcc -

alt -

altAcc -

query -

limit -

Returns:

Result -- this is only minivenues as per the API!

Throws:

FoursquareApiException

venuesTrending

public Result<CompactVenue[]> venuesTrending(String ll,
                                    Integer limit,
                                    Integer radius)
                                      throws FoursquareApiException

Returns a list of venues near the current location with the most people currently checked in.

Parameters:

ll - latitude and longitude of the user's location.

limit - number of results to return, up to 50.

radius - radius in meters, up to approximately 2000 meters.

Returns:

Array of CompactVenue entities wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/venues/trending.html

checkin

public Result<Checkin> checkin(String checkinId,
                      String signature)
                        throws FoursquareApiException

Get details of a checkin.

Parameters:

checkinId - the ID of the checkin to retrieve additional information for.

signature - when checkins are sent to public feeds such as Twitter, Foursquare appends a signature (s=XXXXXX) allowing users to bypass the friends-only access check on checkins. The same value can be used here for programmatic access to otherwise inaccessible checkins.

Returns:

Checkin entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/checkins/checkins.html

checkinsAdd

public Result<Checkin> checkinsAdd(String venueId,
                          String venue,
                          String shout,
                          String broadcast,
                          String ll,
                          Double llAcc,
                          Double alt,
                          Double altAcc)
                            throws FoursquareApiException

Allows you to check in to a place.

Parameters:

venueId - the venue where the user is checking in. No venueid is needed if shouting or just providing a venue name. Find venue IDs by searching or from historical APIs.

venue - if are not shouting, but you don't have a venue ID or would rather prefer a 'venueless' checkin, pass the venue name as a string using this parameter

shout - a message about your check-in. The maximum length of this field is 140 characters.

broadcast - how much to broadcast this check-in, ranging from private (off-the-grid) to public,facebook,twitter. Can also be just public or public,facebook, for example. If no valid value is found, the default is public. Shouts cannot be private.

ll - latitude and longitude of the user's location.

llAcc - accuracy of the user's latitude and longitude, in meters.

alt - altitude of the user's location, in meters.

altAcc - vertical accuracy of the user's location, in meters.

Returns:

Checkin entity wrapped in Result object. Result also contains list of Notifications related to this checkin.

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/checkins/add.html

checkinsRecent

public Result<Checkin[]> checkinsRecent(String ll,
                               Integer limit,
                               Long afterTimestamp)
                                 throws FoursquareApiException

Returns a list of recent checkins from friends.

Parameters:

ll - latitude and longitude of the user's location, so response can include distance.

limit - number of results to return, up to 100.

afterTimestamp - seconds after which to look for checkins

Returns:

Array of Checkin entities wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/checkins/recent.html

checkinsAddComment

public Result<Comment> checkinsAddComment(String checkinId,
                                 String text)
                                   throws FoursquareApiException

Comment on a checkin-in

Parameters:

checkinId - the ID of the checkin to add a comment to

text - the text of the comment, up to 200 characters.

Returns:

Comment entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/checkins/addcomment.html

checkinsDeleteComment

public Result<Checkin> checkinsDeleteComment(String checkinId,
                                    String commentId)
                                      throws FoursquareApiException

Remove a comment from a checkin, if the acting user is the author or the owner of the checkin.

Parameters:

checkinId - the ID of the checkin to remove a comment from.

commentId - the id of the comment to remove.

Returns:

Checkin entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/checkins/deletecomment.html

tip

public Result<CompleteTip> tip(String id)
                        throws FoursquareApiException

Gives details about a tip, including which users (especially friends) have marked the tip to-do or done.

Parameters:

id - id of tip to retrieve

Returns:

CompleteTip entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/tips/tips.html

tipsAdd

public Result<CompleteTip> tipsAdd(String venueId,
                          String text,
                          String url)
                            throws FoursquareApiException

Allows user to add a new tip at a venue.

Parameters:

venueId - the venue where you want to add this tip.

text - the text of the tip.

url - a URL related to this tip.

Returns:

CompleteTip entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/tips/add.html

tipsSearch

public Result<CompleteTip[]> tipsSearch(String ll,
                               Integer limit,
                               Integer offset,
                               String filter,
                               String query)
                                 throws FoursquareApiException

Returns a list of tips near the area specified.

Parameters:

ll - latitude and longitude of the user's location.

limit - number of results to return, up to 500.

offset - used to page through results.

filter - if set to friends, only show nearby tips from friends.

query - only find tips matching the given term, cannot be used in conjunction with friends filter.

Returns:

Array of CompleteTip entities wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/tips/search.html

tipsMarkTodo

public Result<Todo> tipsMarkTodo(String tipId)
                          throws FoursquareApiException

Allows you to mark a tip to-do.

Parameters:

tipId - the tip you want to mark to-do.

Returns:

Todo entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/tips/marktodo.html

tipsMarkDone

public Result<CompleteTip> tipsMarkDone(String tipId)
                                 throws FoursquareApiException

Allows the acting user to mark a tip done.

Parameters:

tipId - the tip you want to mark done

Returns:

CompleteTip entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/tips/markdone.html

tipsUnmark

public Result<CompleteTip> tipsUnmark(String tipId)
                               throws FoursquareApiException

Allows user to remove a tip from your to-do list or done list.

Parameters:

tipId - the tip you want to unmark.

Returns:

CompleteTip entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/tips/unmark.html

photo

public Result<Photo> photo(String id)
                    throws FoursquareApiException

Get details of a photo.

Parameters:

id - the id of the photo to retrieve additional information for.

Returns:

Photo entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/photos/photos.html

photosAdd

public Result<Photo> photosAdd(String checkinId,
                      String tipId,
                      String venueId,
                      String broadcast,
                      String ll,
                      Double llAcc,
                      Double alt,
                      Double altAcc,
                      byte[] data)
                        throws FoursquareApiException

Allows user to add a new photo to a checkin, tip, or a venue in general.

Parameters:

checkinId - the id of a checkin owned by the user

tipId - the id of a tip owned by the user

venueId - the id of a venue, provided only when adding a public photo of the venue

broadcast - twitter, facebook or twitter,facebook if you want to send to both.

ll - latitude and longitude of the user's location.

llAcc - accuracy of the user's latitude and longitude, in meters.

alt - altitude of the user's location, in meters.

altAcc - vertical accuracy of the user's location, in meters.

data - data of the image. Image should be "image/jpeg"

Returns:

Photo entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/photos/add.html

settingSet

public Result<Setting> settingSet(String settingId,
                         Boolean value)
                           throws FoursquareApiException

Change a setting for the given user.

Parameters:

settingId - one of sendToTwitter, sendMayorshipsToTwitter, sendBadgesToTwitter, sendToFacebook, sendMayorshipsToFacebook, sendBadgesToFacebook, receivePings, receiveCommentPings.

value - true or false

Returns:

Setting entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/settings/set.html

settingsAll

public Result<Setting> settingsAll()
                            throws FoursquareApiException

Returns the settings of the acting user.

Returns:

Setting entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/settings/all.html

special

public Result<CompleteSpecial> special(String id,
                              String venueId)
                                throws FoursquareApiException

Gives details about a special, including text and whether it is unlocked for the current user.

Parameters:

id - id of special to retrieve

venueId - id of a venue the special is running at

Returns:

CompleteSpecial entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/specials/specials.html

specialsSearch

public Result<SpecialGroup> specialsSearch(String ll,
                                  Double llAcc,
                                  Double alt,
                                  Double altAcc,
                                  Integer limit)
                                    throws FoursquareApiException

Returns a list of specials near the current location.

Parameters:

ll - latitude and longitude to search near.

llAcc - accuracy of latitude and longitude, in meters.

alt - altitude of the user's location, in meters.

altAcc - accuracy of the user's altitude, in meters.

limit - number of results to return, up to 50

Returns:

SpecialGroup entity wrapped in Result object

Throws:

FoursquareApiException - when something unexpected happens

See Also:

https://developer.foursquare.com/docs/specials/search.html

getAuthenticationUrl

public String getAuthenticationUrl()

Returns user authentication URL

Returns:

user authentication URL

authenticateCode

public void authenticateCode(String code)
                      throws FoursquareApiException

Exchanges code for oAuthToken

Parameters:

code - code

Throws:

FoursquareApiException - when something unexpected happens

getIOHandler

public IOHandler getIOHandler()

Returns current IOHandler

Returns:

current IOHandler