Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 195 lines (153 sloc) 5.706 kB
e60761b @mLewisLogic adding creds example
authored
1 # foursquare
2
06efb1d @mLewisLogic Fondu callout in readme
authored
3 Python wrapper for the [foursquare v2 API](http://developer.foursquare.com/docs/). Originally developed to power [Fondu](http://fondu.com).
e60761b @mLewisLogic adding creds example
authored
4
1659452 @mLewisLogic updated readme
authored
5 Philosophy:
6
7 * Map foursquare's endpoints one-to-one
8 * Clean, simple, Pythonic calls
27ee838 @mLewisLogic doc tweaks
authored
9 * Only handle raw data, you define your own models
1659452 @mLewisLogic updated readme
authored
10
424eeda @mLewisLogic updated README
authored
11 Features:
8d830c6 @mLewisLogic doc improvements
authored
12
6a91aa5 @mLewisLogic test fixing, small doc updates
authored
13 * OAuth dance
424eeda @mLewisLogic updated README
authored
14 * Automatic retries
6c238ea @mLewisLogic doc update
authored
15 * Full endpoint coverage (non-merchant)
16 * Full test coverage
424eeda @mLewisLogic updated README
authored
17 * Useful exception classes
4ba5cf5 @mLewisLogic dox mention multi support
authored
18 * Multi support (via beichhor)
424eeda @mLewisLogic updated README
authored
19
ee82f4a @mLewisLogic updated setup dependencies. cleaned out egg-info
authored
20 Dependencies:
21
22 * httplib2
23 * simplejson (optional)
1659452 @mLewisLogic updated readme
authored
24
e60761b @mLewisLogic adding creds example
authored
25 ## Usage
26
424eeda @mLewisLogic updated README
authored
27 ### Authentication
445bd37 @mLewisLogic doc tweaks
authored
28
29 # Construct the client object
7e319d0 @mLewisLogic oauth dance
authored
30 client = foursquare.Foursquare(client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', redirect_uri='http://fondu.com/oauth/authorize')
27ee838 @mLewisLogic doc tweaks
authored
31
445bd37 @mLewisLogic doc tweaks
authored
32 # Build the authorization url for your app
7e319d0 @mLewisLogic oauth dance
authored
33 auth_uri = client.oauth.auth_url()
424eeda @mLewisLogic updated README
authored
34
445bd37 @mLewisLogic doc tweaks
authored
35 Redirect your user to the address *auth_uri* and let them authorize your app. They will then be redirected to your *redirect_uri*, with a query paramater of code=XX_CODE_RETURNED_IN_REDIRECT_XX. In your webserver, parse out the *code* value, and use it to call client.oauth.get_token()
7e319d0 @mLewisLogic oauth dance
authored
36
445bd37 @mLewisLogic doc tweaks
authored
37 # Interrogate foursquare's servers to get the user's access_token
8d830c6 @mLewisLogic doc improvements
authored
38 access_token = client.oauth.get_token('XX_CODE_RETURNED_IN_REDIRECT_XX')
27ee838 @mLewisLogic doc tweaks
authored
39
7e319d0 @mLewisLogic oauth dance
authored
40 # Apply the returned access token to the client
41 client.set_access_token(access_token)
27ee838 @mLewisLogic doc tweaks
authored
42
6a91aa5 @mLewisLogic test fixing, small doc updates
authored
43 # Get the user's data
7e319d0 @mLewisLogic oauth dance
authored
44 user = client.users()
424eeda @mLewisLogic updated README
authored
45
46 ### Instantiating a client
47 #### [Userless Access](https://developer.foursquare.com/overview/auth)
48 client = foursquare.Foursquare(client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET')
49
6a91aa5 @mLewisLogic test fixing, small doc updates
authored
50 #### [Authenticated User Access](https://developer.foursquare.com/overview/auth) (when you already have a user's access_token)
424eeda @mLewisLogic updated README
authored
51 client = foursquare.Foursquare(access_token='USER_ACCESS_TOKEN')
52
53
54 #### [Specifing a specific API version](https://developer.foursquare.com/overview/versioning)
55 client = foursquare.Foursquare(client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', version='20111215')
950f4a0 @mLewisLogic readme cleanaup
authored
56 or
2b6ba84 @mLewisLogic readme typo
authored
57
424eeda @mLewisLogic updated README
authored
58 client = foursquare.Foursquare(access_token='USER_ACCESS_TOKEN', version='20111215')
59
60
61 ### Examples
62
63 #### Users
64 ##### [Getting your own user object](https://developer.foursquare.com/docs/users/users)
65 client.users()
66 ##### [Getting another user](https://developer.foursquare.com/docs/users/users)
950f4a0 @mLewisLogic readme cleanaup
authored
67 client.users('1183247')
424eeda @mLewisLogic updated README
authored
68 ##### [Get your checkins](https://developer.foursquare.com/docs/users/checkins)
69 client.users.checkins()
70 ##### [Get your most recent checkin](https://developer.foursquare.com/docs/users/checkins)
71 client.users.checkins(params={'limit': 1})
72 ##### Get *all* of your friends' checkins (not a native 4sq call)
950f4a0 @mLewisLogic readme cleanaup
authored
73 client.users.all_checkins('1183247')
424eeda @mLewisLogic updated README
authored
74 ##### [Approve a friend's friend request](https://developer.foursquare.com/docs/users/approve)
950f4a0 @mLewisLogic readme cleanaup
authored
75 client.users.approve('1183247')
424eeda @mLewisLogic updated README
authored
76
77 #### Venues
78 ##### [Get details about a venue](https://developer.foursquare.com/docs/venues/venues)
79 client.venues('40a55d80f964a52020f31ee3')
80 ##### [Search for a coffee place](https://developer.foursquare.com/docs/venues/search)
81 client.venues.search(params={'query': 'coffee'})
82 ##### [Mark a venue to-do](https://developer.foursquare.com/docs/venues/marktodo)
83 client.venues.marktodo('40a55d80f964a52020f31ee3')
84
85 #### Checkins
86 ##### [Get recent checkins for yourself](https://developer.foursquare.com/docs/checkins/recent)
87 client.checkins.recent()
88 ##### [Get recent checkins for a friend](https://developer.foursquare.com/docs/checkins/recent)
950f4a0 @mLewisLogic readme cleanaup
authored
89 client.checkins.recent('1183247')
424eeda @mLewisLogic updated README
authored
90
91 #### Tips
92 ##### [Get a specific tip](https://developer.foursquare.com/docs/tips/tips)
93 client.tips('4b5e662a70c603bba7d790b4')
94 ##### [Search for a tip](https://developer.foursquare.com/docs/tips/search)
95 client.tips.search(params={'query': 'donuts'})
96
97
1659452 @mLewisLogic updated readme
authored
98 ### Full endpoint list
99 Note: endpoint methods map one-to-one with foursquare's endpoints
6145572 @mLewisLogic fixed readme
authored
100
1659452 @mLewisLogic updated readme
authored
101 users()
102 users.leaderboard()
103 users.requests()
104 users.search()
105 users.badges()
106 users.checkins()
950f4a0 @mLewisLogic readme cleanaup
authored
107 users.all_checkins() [*not a native endpoint*]
1659452 @mLewisLogic updated readme
authored
108 users.friends()
109 users.lists()
110 users.mayorships()
111 users.photos()
112 users.venuehistory()
113 users.approve()
114 users.deny()
115 users.request()
116 users.setpings()
117 users.unfriend()
118 users.update()
119
120 venues()
121 venues.add()
122 venues.categories()
123 venues.explore()
124 venues.search()
125 venues.trending()
126 venues.events()
127 venues.herenow()
128 venues.listed()
5077b5b @mLewisLogic multi support (thx beichhor), multi tests, bumped version, updated te…
authored
129 venues.menu()
1659452 @mLewisLogic updated readme
authored
130 venues.photos()
131 venues.similar()
132 venues.tips()
133 venues.flag()
134 venues.marktodo()
135 venues.proposeedit()
136
137 checkins()
138 checkins.add()
139 checkins.recent()
140 checkins.addcomment()
141 checkins.deletecomment()
142
143 tips()
144 tips.add()
145 tips.search()
146 tips.done()
147 tips.listed()
148 tips.markdone()
149 tips.marktodo()
150 tips.unmark()
151
152 lists()
153 lists.add()
154 lists.followers()
155 lists.suggestphoto()
156 lists.suggesttip()
157 lists.suggestvenues()
158 lists.additem()
159 lists.deleteitem()
160 lists.follow()
161 lists.moveitem()
162 lists.share()
163 lists.unfollow()
164 lists.update()
165 lists.updateitem()
166
167 photos()
168 photos.add()
169
170 settings()
171 settings.all()
172 settings.set()
173
174 specials()
175 specials.search()
176 specials.flag()
177
178 events()
179 events.categories()
180 events.search()
5077b5b @mLewisLogic multi support (thx beichhor), multi tests, bumped version, updated te…
authored
181
182 multi()
0301e0b @mLewisLogic cleaned up markdown
authored
183
424eeda @mLewisLogic updated README
authored
184 ## Improvements
185 What else would you like this library to do? Let me know. Feel free to send pull requests for any improvements you make.
1659452 @mLewisLogic updated readme
authored
186
187 ### Todo
188 * Bring in new endpoints as they emerge
8d830c6 @mLewisLogic doc improvements
authored
189 * Test coverage for write methods
1659452 @mLewisLogic updated readme
authored
190 * Merchant-specific endpoints (someday)
191
192 ## License
193 MIT License. See LICENSE
1735d2c @mLewisLogic updated dox
authored
194 Copyright (c) 2012 Mike Lewis
Something went wrong with that request. Please try again.