Package: jodel_api
Inofficial interface to the private API of the Jodel App. Not affiliated
withThe Jodel Venture GmbH.InstallationUsing pip:pip install jodel_apior using setup.py:git clone https://github.com/nborrmann/jodel_api.git
cd jodel_api
python setup.py installUsageAccount CreationCalling the bare constructor creates a new account:>>>importjodel_api>>>lat,lng,city=48.148434,11.567867,"Munich">>>j=jodel_api.JodelAccount(lat=lat,lng=lng,city=city)Creatingnewaccount.get_account_data()returns all data associated with this account
(censored by me):>>>j.get_account_data(){'access_token':'xxx','expiration_date':1472660000,'refresh_token':'xxx','distinct_id':'xxx','device_uid':'xxx'}Save this data to reuse the account later on, feed it to the
JodelAccount() constructor to reinitiate the account. This constructor
issues one request to update the location of the account.>>>j=jodel_api.JodelAccount(lat=lat,lng=lng,city=city,access_token='xxx',expiration_date='xxx',refresh_token='xxx',distinct_id='xxx',device_uid='xxx',is_legacy=True)(204,'')Addupdate_location=Falseto suppress this behaviour. The
constructor will only instantiate an object, without making any remote
calls:>>>j=jodel_api.JodelAccount(lat=lat,lng=lng,city=city,update_location=False,**account_data)Afterexpiration_datehas passed, callrefresh_access_tokens()to re-authenticate. Ifrefresh_access_tokenfails, userefresh_all_tokensinstead (this is akin to creating a new account,
but preserves the account’s data (karma, etc)):>>>j.refresh_access_token()(200,{'token_type':'bearer','access_token':'xxx','expires_in':604800,'expiration_date':xxx})>>>j.refresh_all_tokens()(200,{'expires_in':604800,'access_token':'xxx','token_type':'bearer','returning':True,'refresh_token':'xxx','expiration_date':1472600000,'distinct_id':'xxx'})Account VerificationFor some functionality like voting and posting (look out for error 478)
accounts need to be verified.With Jodel version4.48captcha verification has been disabled.
However old accounts will continue to work with version4.47. But if you
ever use an old, verified account with version4.48it will become
unverified. To this end, use the flagis_legacy=Truein the
constructor when you instantiate an old account (on by default). New
accounts must be created withis_legacy=False.In4.48accounts can only be verified through Google Cloud Messaging.
The steps are as follows:Create an Android Account:a = jodel_api.AndroidAccount()Request a push token:a.get_push_token()Send push token to Jodel Servers:j.send_push_token(token)Log into GCM and read push messages (verification_code) from
Jodel:verification = a.receive_verification_from_gcm()Send the verification code to Jodel to verify the account:a.verify_push(server_time, verification_code)Injodel_apithis is implemented as follows:a=jodel_api.AndroidAccount()j.verify(a)Tip: If the call is successful, save the account credentials and reuse
them later (if you getREGISTRATION_INVALIDretry with another
account):account_id,security_token=a.android_id,a.security_tokena2=jodel_api.AndroidAccount(account_id,security_token)API callsAll remote API calls return a tuple of HTTP status_code and the
response (if possible a dict, parsed from the API response), but might
also be a string (error message).The following API calls are supported (presented without their
respective responses):# API methods for reading posts:>>>j.get_posts_recent(skip=0,limit=60,after=None,mine=False,hashtag=None,channel=None)>>>j.get_posts_popular(skip=0,limit=60,after=None,mine=False,hashtag=None,channel=None)>>>j.get_posts_discussed(skip=0,limit=60,after=None,mine=False,hashtag=None,channel=None)>>>j.get_pictures_recent(skip=0,limit=60,after=None)>>>j.get_pictures_popular(skip=0,limit=60,after=None)>>>j.get_pictures_discussed(skip=0,limit=60,after=None)>>>j.get_my_pinned_posts(skip=0,limit=60,after=None)>>>j.get_my_replied_posts(skip=0,limit=60,after=None)>>>j.get_my_voted_posts(skip=0,limit=60,after=None)>>>j.post_search(message,skip=0,limit=60)# API methods for interacting with single posts:>>>j.create_post(message=None,imgpath=None,b64img=None,color=None,ancestor=None,channel="")>>>j.get_post_details(post_id)# This endpoint has been deprecated. Use get_post_details_v3.>>># This api endpoint implements paging and returns at most 50 replies,>>># use the skip parameter to page through the thread:>>>j.get_post_details_v3(post_id,skip=0)>>>j.upvote(post_id)>>>j.downvote(post_id)>>>j.give_thanks(post_id)>>>j.get_share_url(post_id)>>>j.pin(post_id)>>>j.unpin(post_id)>>>j.enable_notifications(post_id)>>>j.disable_notifications(post_id)>>>j.delete_post(post_id)# Only works on your own posts ಠ_ಠ# API methods for interacting with sticky posts:>>>j.upvote_sticky_post(post_id)>>>j.downvote_sticky_post(post_id)>>>j.dismiss_sticky_post(post_id)# API methods for interacting with notifications:>>>j.get_notifications()>>>j.get_notifications_new()>>>j.notification_read(post_id=None,notification_id=None)# API methods for interacting with channels:>>>j.get_recommended_channels()>>>j.get_channel_meta(channel)>>>j.follow_channel(channel)>>>j.unfollow_channel(channel)# API methods for interacting with your user profile:>>>j.set_location(lat,lng,city,country=None,name=None)# country and name appear to have no effect>>>j.set_user_profile(user_type=None,gender=None,age=None)>>>j.get_user_config()>>>j.get_karma()>>>j.get_captcha()>>>j.submit_captcha(key,answer)The parametersskip,limitandafterimplement paging. Whileskipandlimitare integers,afteris apost_idparameter and will return all
jodels that follow that one. The former two paramters seem to be
deprecated in favor of the latter, howeverafterdoesn’t work
on all/mine/endpoints (ie.mine=Trueorget_my_x_posts).The argumentsmine(boolean),hashtag,channel(both strings)
are exclusive. Ifmineevaluates totrue, the other two arguments
are discarded, ifhashtagevaluatestrue,channelis
discarded.post_search()is a new endpoint (as of June 17) that isn’t yet
available through the app. It returns all posts from your location
that contain a given string.You can pass additional arguments (such as proxies and timeouts) to all
API calls through the**xargsargument that will be passed to therequests.request()function:>>>j.upvote(post_id,timeout=5,proxies={'https':'127.0.0.1:5000'})For unimplemented endpoints, checkissue #22.Error Codes401 “Unauthorized”: Youraccess_tokenis invalid. Either
you messed up, or it is outdated. You need to callrefresh_access_token()orrefresh_all_token()(check the
above section on account creation).401 “Action not allowed”: You are using a4.48account
withis_legacy=True, but4.48accounts are not allowed
to downgrade.403 “Access Denied”: Your IP is banned accross endpoints,
just read-only endpoints still work. Effective for 24 hours.429 “Too Many Requests”: Your IP is rate-limited. Applies only
to one specific endpoint.477 “Signed Request Expected”: This library should handle request
signing. Make sure to upgrade to the latest version ofjodel_api,
as the signing key changes every few weeks.478 “Account not verified”: Verify the account through GCM.502 “Bad Gateway”: Something went wrong server-side. This happens
pretty randomly.jodel_apiautomatically retries two times when
it sees this error. If you encounter this status, the jodel servers
are probably having issues. Try again later.Rate-LimitsThe Jodel API appears to have the following (IP-based) rate-limitsmax of 200 new account registrations from one IP per half hourmax of 200 votes per minutemax of 100 captcha requests per minuteThey also hand out 403 bans if you overdo it.TestsNearly all tests injodel_api_test.pyare integration tests, which
actually hit the Jodel servers. These can fail for any number of reasons
(eg. connectivity issues), which does not necessarily imply there is
something wrong with this library. As this library tries to make few
assumptions about the content of the json responses they test mostly for
status codes, not the contents of the responses (ie. they test whether
the API endpoints are still valid).For the tests inclass TestUnverifiedAccounta new account is
created on every run and they test GCM verification, posting and
read-only functionsTests inclass TestLegacyVerifiedAccountneed an already verified
legacy account and test if it still works.
To run these tests you need to verify an account by
solving the captcha and save itsdevice_uidin the
environment variableJODEL_ACCOUNT_LEGACY. Runj.get_account_data()['device_uid']to get the value.Linux:export JODEL_ACCOUNT_LEGACY=a8aa02[...]dbaWindows (you need to restart the cmd/shell for this to take effect,
or set it through gui):setx JODEL_ACCOUNT_LEGACY a8aa02[...]dbaIf this variable is not present, these tests will be skipped.Clone the directory, install the library and run the tests withpythonsetup.pytest