/Tinder

Official November 2019 Documentation for Tinder's API (wrapper included)

Primary LanguagePythonMIT LicenseMIT

Tinder API Documentation - 2018

First off, I want to give a shoutout to @rtt who initially posted the Tinder API Documentation that I found most of these endpoints on. I am writing this to provide a more up-to-date resource for working with the Tinder API.

Note: This was updated in June 2018 so it might be outdated.

API Details

Host api.gotinder.com
Protocol SSL

Required Headers

Header Example Notes
X-Auth-Token See "How to get facebook_token" below
Content-type application/json Shouldn't be sent to `/like/_id` nor `/pass/_id` (#63)
User-agent Tinder/7.5.3 (iPhone; iOS 10.3.2; Scale/2.00)

Known Endpoints

Note: All endpoints are concatenated to the host url

Note: All curls must be sent with the headers as well (the only exception is that the /auth call must not have the X-Auth-Token header)

Endpoint Purpose Data? Method
/auth For authenticating {'facebook_token': INSERT_HERE, 'facebook_id': INSERT_HERE} POST
/v2/auth/sms/send?auth_type=sms Part 1 of SMS authentication (two-factor) {'phone_number': string} POST
/v2/auth/sms/validate?auth_type=sms Part 2 of SMS authentication (two-factor) {'otp_code': string, 'phone_number': string } POST
/v2/auth/login/sms Part 3 of SMS authentication (two-factor) {'refresh_token': string} POST
/user/recs Get match recommendations {} GET
/v2/matches Get your matches query in link should have count=1-100 e.g: /v2/matches?count=50 GET
/user/matches/_id Send Message to that id {"message": TEXT GOES HERE} POST
/user/matches/match_id Unmatch person {} DELETE
/user/_id Get a user's profile data {} GET
/user/ping Change your location {"lat": lat, "lon": lon} POST
/updates Get all updates since the given date -- inserting "" will give you all updates since creating a Tinder account (i.e. matches, messages sent, etc.) {"last_activity_date": ""} Input a timestamp: '2017-03-25T20:58:00.404Z' for updates since that time. POST
/profile Get your own profile data {} GET
/profile Change your search preferences {"age_filter_min": age_filter_min, "gender_filter": gender_filter, "gender": gender, "age_filter_max": age_filter_max, "distance_filter": distance_filter} POST
/profile (Tinder Plus Only) hide/show age {"hide_age":boolean} POST
/profile (Tinder Plus Only) hide/show distance {"hide_distance":boolean} POST
/profile (Tinder Plus Only) hide/show ads {"hide_ads":boolean} POST
/profile (Tinder Plus Only) Set Tinder Blend options to "Recent Activity": Shows more recently active users {"blend":"recency"} POST
/profile (Tinder Plus Only) Set Tinder Blend options to "Optimal": Scientifically proven to get you more matches {"blend":"optimal"} POST
/profile (Tinder Plus Only) Set discovery settings to only people who already liked you {"discoverable_party":"liked"} POST
/passport/user/travel (Tinder Plus Only) Travel to coordinate {"lat":lat,"lon":lon} POST
/v1/activity/feed?direction=past&eventTypes=1023 Get activity feed, including old and updated bios for comparison {} GET
/instagram/authorize Auth Instagram {} GET
/v2/profile/spotify/ Get Spotify settings {} GET
/v2/profile/spotify/theme Set Spotify song {"id":song_id} PUT
/profile/username Change your webprofile username {"username": username} PUT
/profile/username Reset your webprofile username {} DELETE
/meta Get your own meta data (swipes left, people seen, etc..) {} GET
/v2/meta Get your own meta data from V2 API (extra data like "top_picks" info) {} GET
/report/_id Report someone --> There are only a few accepted causes... (see tinder_api.py for options) {"cause": cause, "text": explanation} POST
/like/_id Like someone a.k.a swipe right {} GET
/pass/_id Pass on someone a.k.a swipe left {} GET
/like/_id/super ~Super Like~ someone a.k.a swipe up {} POST
/matches/{match id} Get a match from its id (thanks @jtabet ) {} GET
/message/{message id} Get a message from its id (thanks @jtabet ) {} GET
/passport/user/reset Reset your location to your real location {} POST
/passport/user/travel Change your swiping location {"lat": latitutde, "lon": longitude} POST
/user/{user_id}/common_connections Get common connection of a user {} GET
/profile/job Set job {"company":{"id":"17767109610","name":"University of Miami","displayed":true},"title":{"id":"106123522751852","name":"Research Assistant","displayed":true}} PUT
/profile/job Delete job {} DELETE
/profile/school Set school(s) {"schools":[{"id":school_id}]} PUT
/profile/school Reset school {} DELETE
/message/{message_id}/like Like a message {} POST
/v2/fast-match/preview Get the non blurred thumbnail image shown in the messages-window (the one showing the likes you received) {} GET
/v2/fast-match/count Get the number of likes you received {} GET
/giphy/trending?limit={limit} Get the trending gifs (tinder uses giphy) accessible in chat {} GET
/giphy/search?limit={limit}&query={query} Get gifs (tinder uses giphy) based on a search accessible in chat {} GET

Status Codes

Status Code Explanation
200 Everything went okay, and returned a result (if any).
301 The server is redirecting you to a different endpoint. This can happen when a company switches domain names, or an endpoint's name has changed.
400 The server thinks you made a bad request. This can happen when you don't send the information the API requires to process your request, among other things.
401 The server thinks you're not authenticated. This happens when you don't send the right credentials to access an API
404 The server didn't find the resource you tried to access.
503 Back-end server is at capacity.

Config File

facebook_access_token and fb_user_id

Simply input your facebook username/email and password in your config file. Then, the fb_auth_token.py module will programmatically retrieve your facebook_access_token and fb_user_id. These are then used to generate your tinder_auth_token in tinder_api.py which grants you access to your data! Happy Swiping!

SMS Authentication (implemented by @Tagge)
SMS authentication is even easier. Just run phone_auth_token.py . You'll be asked your phone number at runtime, you'll then have to type in the code you received by SMS, and it will return your token. We didn't directly implement it in the tinder_api.py because, as opposed to Facebook auth, there's a rate limit to the number of SMS you can receive in an hour (actually 60). It's therefore better to get your token once and use it within its lifetime (24 hours) rather than asking for a new one everytime.
With your token ready, add it to tinder_config_ex.py (value for tinder_token). You're now ready to roll !

Note: With the help of philliperemy , I have included a programatic way to acquire your facebook_token. Now, in your config.py just input your facebook username and password.

Note: With the help of gloriamacia , we added now a jupyter notebook to make the usage even simpler.

Key Features

Match_Info:

Creates a local dictionary containing the following keys on each of your matches

{
	  123456: {
	    'messages': [

	    ],
	    'age': 20,
	    'match_id': '123456789123456789',
	    'name': 'Joakim',
	    'photos': [
	      'http://images.gotinder.com/123456789123456789.jpg',
	      'http://images.gotinder.com/123456789123456789.jpg',
	      'http://images.gotinder.com/123456789123456789.jpg',
	      'http://images.gotinder.com/123456789123456789.jpg'
	    ],
	    'message_count': 0,
	    'last_activity_date': '15 days, 16 hrs 46 min 57 sec',
	    'ping_time': '2017-03-11T04:58:56.433Z',
	    'gender': 1,
	    'bio': 'New York Knicks Center',
	    'avg_successRate': 0
	  },
	  56789: {
	    ...
	  }
}

Sorting:

Sorting matches by "age", "message_count", and "gender"

[
	  ('123456789123456789',
	  {
	    'messages': [

	    ],
	    'age': 19,
	    'match_id': '123456789123456789abcdefghi',
	    'name': 'Carmelo',
	    'photos': [
	      'http://images.gotinder.com/123456789123456789.jpg',
	      'http://images.gotinder.com/123456789123456789.jpg',
	      'http://images.gotinder.com/123456789123456789.jpg',
	      'http://images.gotinder.com/123456789123456789.jpg'
	    ],
	    'message_count': 0,
	    'last_activity_date': '0 days, 22 hrs 23 min 45 sec',
	    'ping_time': '2017-03-25T23:22:08.954Z',
	    'gender': 1,
	    'bio': 'I do not like to win sometimes', 'avg_successRate': 0.7837966008217391
	    }
	    )
]

The following is no longer available due to Tinder setting their ping_time to a constant date in 2014 and/or the removal of Tinder Social.

```

Friends' Pingtimes:

friends_pingtimes() will return the following for each facebook friend of yours who has a Tinder friend_pingtime_by_name("Joakim Noah") will return the pingtime for only that particular friend. The following is a sample result for friends_pingtimes():

"Joakim Noah -----> 15 days, 16 hrs 46 min 57 sec" "Carmelo Anthony ------> 0 days, 22 hrs 23 min 45 sec" ...

Facebook Friends:

Given a name, it returns some profile information and their id. Once you have the ID, then you can call api.get_person(id) to get more in-depth information on your friends.

{
	  'Martin Shkreli': {
	    'photo': [
	      {
	        'processedFiles': [
	          {
	            'url': 'https://graph.facebook.com/123456789/picture?height=84&width=84',
	            'height': 84,
	            'width': 84
	          },
	          {
	            'url': 'https://graph.facebook.com/123456789/picture?height=172&width=172',
	            'height': 172,
	            'width': 172
	          },
	          {
	            'url': 'https://graph.facebook.com/123456789/picture?height=320&width=320',
	            'height': 320,
	            'width': 320
	          },
	          {
	            'url': 'https://graph.facebook.com/123456789/picture?height=640&width=640',
	            'height': 640,
	            'width': 640
	          }
	        ]
	      }
	    ],
	    'in_squad': True,
	    'name': 'Martin Shkreli',
	    'user_id': '582bf320452u3yy1217f8'
	  }
}