-
Notifications
You must be signed in to change notification settings - Fork 57
/
apiary.apib
4560 lines (3728 loc) · 165 KB
/
apiary.apib
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
FORMAT: 1A
HOST: https://api.simkl.com
# Simkl API
<table>
<tr>
<td width="85" align="center" valign="top"><a href="https://simkl.com" target="_blank"><img src="https://i.simkl.com/img_tv/apiary_logo_api.png" alt="Simkl" width="68" height="67"/></a></td>
<td>We’ve worked very hard to make <a href="https://simkl.com/" target="_blank">Simkl</a> the dream "TV, Anime and Movie Tracker". However, chances are it doesn’t do 100% of what you need it to do. Luckily for you, we added an API so you can extend Simkl’s functionality.<br><br>If you need some API method which we do not have, do not hesitate to <a href="mailto:[email protected]" target="_blank">contact us</a> and we'll add it as soon as possible. </td>
</tr>
<tr>
<td colspan="2"><br><b>Useful Links:</b><br>
<a href="https://simkl.com/">Simkl.com</a> ∙
<a href="https://simkl.com/settings/developer/new/">Get an API key</a> ∙
<a href="https://discord.gg/MJsWNE4">Feature Requests</a> ∙
<a href="https://discord.gg/MJsWNE4">Discord Server</a> ∙
<a href="https://github.com/SIMKL/API/issues">Report Issues</a> ∙
<a href="https://twitter.com/Simkl">Twitter</a>
</table>
# Getting Started
***
This guide will walk you through how to use Simkl API on your website, media server app, browser extension or in your mobile app.
## Before You Start
To successfully start using Simkl API, you need to:
1. **[Sign up for a Simkl account](https://passport.simkl.com/register/)**.
2. **[Create a new app in your account](https://simkl.com/settings/developer/new/)** to get your API key (`client_id`).
3. **[Join the Discord Server to chat](https://discord.gg/MJsWNE4)**
<br><br>Join the [community](https://discord.gg/MJsWNE4) to talk, learn about and discuss the Simkl APIs. Or DM directly on Discord.
## Requirements
### 1. When using the API, a link is required back to https://simkl.com/ or directly to an item related to the API request. If not sure how to implement, let us know at [email protected] or DM directly on Discord.
### 2. The Simkl API is not authorized for use in conjunction with other competing services of the same nature if your service or app does not provide Simkl login and Sync functionality with Simkl, including but not limited to TV, Movie, Anime, Manga list/tracker services. If you are interested in using this service within your own application or website, please contact us at though our Discord and we will be happy to discuss it further!
What this means is that you cannot use parts of the API that don't involve tracking unless you integrate the option to sync with Simkl, especially if your app already has sync functionality with other trackers.
### 3. Please use TVDB, TMDB API from their original sources if your need metadata API.
### 4. If you're using Github, it is important to hide your Client-ID and secrets in [Github Secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) to avoid any API request limit issues.
### 5. Free for non-commercial use. (See commercial usage below).
The Simkl API can be used within commercial applications or services that generate less than $150 per month in revenue free of charge, without explicitly requesting permission.
Any application or service that generates more than $150 in revenue per month must obtain a commercial license. Those who wish to acquire a commercial license or more information regarding commercial API usage may reach us through the Discord server.
Running the API inside your app with large amount of requests costs us fees in DNS, Routing, Health checks, CDN, Server Hosting, Failover backups and Server management so if you have large amount of requests you need to be able to cover them financially.
## How to use the API
1. Get user's `token` using [OAuth](/#reference/authentication-oauth-2.0) or [PIN Authentication](/#reference/authentication-pin) and save it on user's device.
2. Post API requests with the user's `token` and your API Key (`client_id`)
<br><br><br><br>
# About Simkl API
***
All API access is over HTTPS. All responses are returned as JSON. The API is (mostly) RESTful.<br>
Please [contact us](http://support.simkl.com) if you're interested in an API we don't yet support.
Here's what you need to know to get started quickly:
## Use Cases
The Simkl API lets you build a variety of applications and scripts to integrate Simkl with your apps, show Simkl data in other contexts, and update your watch history from various locations.
Here are some examples of the things you can build with the Simkl API:
- A browser extension to quickly mark as watched or add to your watchlist from any web page.
- A Movie, TV or Anime app for iOS or Android.
- Plugin for your favorite media center app to sync your watch history with Simkl.
## Api URL
`https://api.simkl.com/`
## Verbs
HTTP Verb|Description
---|----
`GET`| Retrieve the item. Success returns `200` status code.
`POST`| Create a new item. Success returns `201` status code.
`DELETE`| Delete the item. Success returns `200` or `204` status code.
## HTTP Status Codes
The Simkl API attempts to return appropriate HTTP status codes for every request.
Code|Text|Description
---|---|----
`200`| OK | Success!
`201`| OK | Success - *new resource created (POST)*
`204`| OK | Success - *no content to return (DELETE)*
`302`| Found | Redirected to correct URL
`400`| Bad Request | The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
`401`| Unauthorized | [Authentication credentials](#reference/authentication-oauth-2.0) were missing or incorrect.
`403`| Forbidden | The request is understood, but it has been refused or access is not allowed. An accompanying error message will explain why. This code is used whe using invalid API key or unapproved app or requests are being denied due to API limits.
`404`| Not Found | The URI requested is invalid or the resource requested. Also returned when the requested format is not supported by the requested method.
`405`| Not Found | *[IN_DEV]*
`409`| Unauthorized | *[IN_DEV]* Conflict - resource already created
`412`| client_id_failed | incorrect cliend_id or Total Requests Limit Exceeded
`422`| *[IN_DEV]* | *[IN_DEV]*
`429`| *[IN_DEV]* | Rate Limit Exceeded
`500`| Internal Server Error | Something is broken. Please post to the [developer discord](https://discord.gg/MJsWNE4) so the Simkl team can investigate.
`502`| Bad Gateway | Simkl is down or being upgraded.
`503`| Service Unavailable | The Simkl servers are up, but overloaded with requests. Try again later.
## Required Headers
When making API calls you'lll need to send some headers to identify your app.
Header|Value
---|----
`Content-Type` * | `application/json`
`simkl-api-key` * | Your `client_id` listed under [your Simkl applications](https://simkl.com/settings/developer/).
## Full Info
By default methods are not returnig additional data for movies, anime, show etc. They return minimal info you need to match in the local database. But, if you need more information just add `extended={fields}` to the URL.
*Fields*|*Description*
---|---|----
`full`| Complete info, except `discover` endpoints
`title`,`slug`,`overview`,`metadata`,`theater`,`genres`,`tmdb`| Possible comma separated values for the <b>Discover</b> endpoints. <br> `theater` value requires `&user-country=us` variable, otherwise US country will be taken.
## Dates
[In Development] Currently dates are returned as (GMT - 05:00 New York time zone)
All dates will be GMT and returned in the ISO 8601 format like `2015-03-15T15:30:11Z`. Adjust
accordingly in your app for the user's local timezone.
## Pagination
Some of our endpoints are paginated. Endpoints which have 📄 Pagination will load 1 page of 10 items by default. If you want to change this, append query string `?page={page}&limit={limit}` to the URL
Parameter|Type|Default|Value
---|---|---|---
`page`|integer|1|Number of page
`limit`|integer|10|Results per page
additionally, all paginated endpoints will return these HTTP headers as well
Header|Value
-|-
X-Pagination-Page|Current page
X-Pagination-Limit|Items per page
X-Pagination-Page-Count|Total number of pages
X-Pagination-Item-Count|Total number of items
## Images
Use `https://wsrv.nl/?url=https://simkl.in` domain for images.
It is preffered to use https://wsrv.nl/ service to minimise traffic to our servers. As an extra bonus WSRV provides options to resize and cut images as you need them.
We have different types of images, choose the one that best suits your needs.
JSON DATA|Prefix URL
---|---
poster|`/posters/`
fanart|`/fanart/`
episode|`/episodes/`
avatars|`/avatars/`
[IN DEV]|`/comments/`
Url structure: <b>{domain}{prefix}{image_url}{suffix}{extension}</b>
prefix|suffix|Size|extension|Example
---|---|---|---|---
`posters`|`_w` (landscape, cropped}|600x338|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/posters/74/74415673dcdc9cdd_w.webp)
`posters`|`_m`|340x *|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/posters/74/74415673dcdc9cdd_m.webp)
`posters`|`_ca`|190x279(285)|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/posters/74/74415673dcdc9cdd_ca.webp)
`posters`|`_c`|170x250(256)|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/posters/74/74415673dcdc9cdd_c.webp)
`posters`|`_cm`|84x124|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/posters/74/74415673dcdc9cdd_cm.webp)
`posters`|`_s`|40x57|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/posters/74/74415673dcdc9cdd_s.webp)
||||
`fanart`|`_d` (darker, small KB)|* x * (original size)|`.jpg`|[Example](https://wsrv.nl/?url=https://simkl.in/fanart/71/710408ec0a1bd207_d.jpg)
`fanart`|`_medium`|1920x1080|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/fanart/71/710408ec0a1bd207_medium.webp)
`fanart`|`_mobile`|960x540|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/fanart/71/710408ec0a1bd207_mobile.webp)
`fanart`|`_w`|600x338|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/fanart/71/710408ec0a1bd207_w.webp)
`fanart`|`_s48`|48x27|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/fanart/71/710408ec0a1bd207_s48.webp)
||||
`episodes`|`_w`|600x338|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/episodes/26/265319260301d2ee2_w.webp)
`episodes`|`_c`|210x118|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/episodes/26/265319260301d2ee2_c.webp)
`episodes`|`_m`|112x63|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/episodes/26/265319260301d2ee2_m.webp)
||||
`avatars`|`_24`|24x24|`.jpg`|[Example](https://wsrv.nl/?url=https://simkl.in/avatars/1/1_24.jpg)
`avatars`|`_100`|100x100|`.jpg`|[Example](https://wsrv.nl/?url=https://simkl.in/avatars/1/1_100.jpg)
`avatars`|` `|200x200|`.jpg`|[Example](https://wsrv.nl/?url=https://simkl.in/avatars/1/1.jpg)
`avatars`|`_256`|256x256|`.jpg`|[Example](https://wsrv.nl/?url=https://simkl.in/avatars/1/1_256.jpg)
`avatars`|`_512`|512x512|`.jpg`|[Example](https://wsrv.nl/?url=https://simkl.in/avatars/1/1_512.jpg)
### Caching images
It is required that you cache images in your app or server by `image_url` forever. The images with the same URL never change. Do not redownload the same image multiple times.
## Standard Media Objects
All methods will accept or return standard media objects for `movie`, `show`, `episode` items.
Anime can has `anime_type` with possible values `tv|movie|special|ova|ona|music video`.
Here are examples for all objects:
<table>
<tr>
<td align="center" valign="top"><strong>movie</strong></td>
<td>
<pre>Movie example:<code>{
"title":"Terminator 3: Rise of the Machines",
"year":2003,
"ids":{
"simkl":53536,
"imdb":"tt0181852",
"tmdb":296
}
}</code></pre>
<pre>Example when only id is known:<code>{
"ids":{
"simkl":53536
}
}</code></pre></td>
</tr>
<tr>
<td align="center" valign="top"><strong>show</strong></td>
<td><pre>TV Show example:<code>"title":"The Walking Dead",
"year":2010,
"ids":{
"simkl":2090,
"tvdb":153021,
"imdb":"tt1520211"
},
"seasons": [
{
"number": 1,
"episodes": [
{
"number": 1
},
{
"number": 2
}
]
}
]
]
}</code></pre>
<pre>Anime example:<code>{
"title": "Attack on Titan",
"year": 2013,
"ids": {
"simkl": 39687,
"mal": 16498,
"tvdb": 267440,
"imdb": "tt2560140",
"anidb": 9541
},
"episodes": [
{
"number": 1
},
{
"number": 2
}
]
}</code></pre></td>
</tr>
<tr>
<td align="center" valign="top"><strong>episode</strong></td>
<td>
<pre>Episode example:<code>{
{
"watched_at": "2014-09-01 09:10:11",
"ids": {
"simkl": 231223,
"hulu": 681868,
"crunchyroll": 656647
}
}
}</code></pre>
</table>
## API Terms of Use
Thank you for using the Simkl application programming interfaces (the "Simkl APIs"). By using the Simkl APIs, you UNCONDITIONALLY CONSENT AND AGREE TO BE BOUND BY AND A PARTY TO THE TERMS AND CONDITIONS LISTED AT [https://simkl.com/about/policies/terms/api/](https://simkl.com/about/policies/terms/api/) and also agree to display information about Simkl in all parts of your application or website where Simkl API or content from Simkl API is used as deemed necessary by request of Simkl Team. If you disagree with any of these terms, Simkl does not grant you a license to use the Simkl APIs.
## Help us improve!
If you find any error or omission on the documentation, or you’d like us to cover or clarify something, just [let us know](https://support.simkl.com/forums/264009-top-ideas-from-the-community/category/86437-api) and we’ll try to make you happy. You are also welcome to [join our development community](https://discord.gg/MJsWNE4).
<br><br>
# Group Authentication - OAuth 2.0
There's no reinventing the wheel here so the API uses OAuth2.
Requesting user associated information requires `token` that needs to be included in all request headers made to the API.
To obtain the `client_id` and `client_secret` please [create an app first](https://simkl.com/settings/developer/new/).
To make calls on behalf of a user you have to obtain an `access_token`. To do this, first use **https://simkl.com/oauth/authorize** method to get `code` and then post it in JSON format to **https://api.simkl.com/oauth/token** url. In response you'll get the `access_token`.
For more details see Authorize and Token sections below.
**So STEP 1 for OAuth - Open the URL that looks like this in your Browser or in a Custom Tab (do not use WebView) on mobile device from your app:**
+ Request https://simkl.com/oauth/authorize?response_type=code&client_id=c7be48f1559a6d794w1925237c626326c7bsdfsa559a6d794w1925137c626316&redirect_uri=http://yourdomain.com/oauth.html
+ Response 200
It will redirect back to your website or app URL with `?code` at the end of your Redirect URL.
## Authorize [/oauth/authorize{?response_type,client_id,redirect_uri,state}]
### Authorize Application [GET]
Redirect a user to this URL. There the user will grant permissions for you app and if everything is fine you'll get a `code` which you can exchange for `access_token`.
Once you have an access token you can use it to make calls on behalf of a user.
**Note:** You should use the https://simkl.com domain when creating this URL and not the API URL.
+ Parameters
+ response_type (string, `code`) ... must be "code"
+ client_id (string) ... Get this from your app settings
+ redirect_uri (string, `http://yourdomain.com/oauth.html`) ... [URI in your app settings](https://simkl.com/settings/developer/)
+ state (optional, string, `state`) ... your custom variable
+ Request https://simkl.com/oauth/authorize?response_type=code&client_id=c7be48f1559a6d794w1925237c626326c7bsdfsa559a6d794w1925137c626316&redirect_uri=http://yourdomain.com/oauth.html
+ Body
+ Response 200
+ Body
## Token [/oauth/token]
### Exchange code for access_token [POST]
**STEP 2:** The redirect to your application in the step above will include a `code` parameter which you can exchange for an `access_token` using this method.
Save the `access_token` somewhere safe. From that moment your app can authenticate the user by sending the `Authorization` header.
<h4>JSON POST DATA</h4>
Key|Type|Value
---|----|-----
code|string|code you've get from authorize method
client_id|string|Get this in your app settings
client_secret|string|Get this in your app settings
redirect_uri|string|Your URI in your app settings
grant_type|string|`authorization_code`
`access_token` do not have expiration date (Never expire).
`access_token` can be deleted by user when revoking app access rights in [Connected Apps settings](https://simkl.com/settings/connected-apps/).
+ Request (application/json)
{
"code" : "d7be48f1559a6d794w1925237c626326c7dddfsa559a6d794w1925137c626313",
"client_id" : "c7be48f1559a6d794w1925237c626326c7bsdfsa559a6d794w1925137c626352",
"client_secret" : "a9be48f1529a2d794w1925237c626326c7dddfsa559a6d794w1925137c626321",
"redirect_uri" : "http://yourdomain.com/oauth.html",
"grant_type" : "authorization_code"
}
+ Response 200 (application/json)
Valid `code` will generate you the `access_token`
+ Body
{
"access_token" : "b5be48f1529a2d794f1925237c626326c7dddfsa559a6d794w1925137c622329",
"token_type" : "bearer",
"scope" : "public"
}
+ Response 401 (application/json)
Invalid code will give you a 401 error
+ Body
{
"error" : "grant_error"
}
# Group Authentication - PIN
This flow is designed for devices that have limited input capabilities, such as media center plugins, game consoles, smart watches, smart TVs, command line scripts, and system services, etc.
Your app displays an alphanumeric code (typically 5 characters) to the user. They are then instructed to visit the verification URL on their computer or mobile device. After entering the code, the user will be prompted to grant permission for your app. After your app gets permissions, the device receives an access_token and works like standard OAuth from that point on.
You should do the following step to authorize user's device:
1. [Request a device code](#reference/authentication-pin/request-a-device-code/get-code).
2. Display `user_code` and instruct the user to visit the [`verification_url`](https://simkl.com/pin/).
<img src="https://us.simkl.in/img_tv/api_demo_pin.png" alt="Simkl PIN" width="779" height="479"/>
3. [Begin polling Simkl's authorization server](#reference/authentication-pin/get-code-status/check-user_code).
4. User enters `user_code` at the [`verification_url`](https://simkl.com/pin/) on their computer or mobile device.
5. Simkl returns `access_token` to the device where the polling is in progress. Your app will be polling to see if the user successfully authorizes your app. Use `expires_in` to stop polling after that many seconds, and gracefully instruct the user to restart the process. **It is important to poll at the correct interval and also stop polling when expired**.
6. Once they have, refresh your UI to indicate a successful connection has been made.
## Request a device code [/oauth/pin{?client_id,redirect}]
### Get CODE [GET]
In response you'll get `user_code` and `verification_url` (in most cases [https://simkl.com/pin/](https://simkl.com/pin/)) which should be displayed to the user. Store `expires_in` and `interval` values for step 3.
<h4>JSON POST DATA</h4>
Key|Type|Value
---|----|-----
client_id|string|Get this in your app settings
+ Parameters
+ client_id (string, `***`) ... Get this from your app settings
+ redirect (string,optional,`http://yourdomain.com/welcome`) ... URL where you want to redirect user when he approved you application
+ Response 200 (application/json)
+ Body
{
'result': 'OK',
'device_code': DEVICE_CODE,
'user_code': USER_CODE,
'verification_url': https://simkl.com/pin/,
'expires_in': 900,
'interval': 5
}
## Get CODE status [/oauth/pin/{USER_CODE}{?client_id}]
### Check USER_CODE [GET]
Application can poll this url to get `USER_CODE` status or `ACCESS_TOKEN`. Returned interval in step 1 response specifies the minimum amount of time(seconds), that your app should wait between polling requests.
+ Parameters
+ client_id (string, `***`) ... Get this from your app settings
+ USER_CODE (string) ... Get this from previous step
+ Response 200 (application/json)
+ Body
{
'result': 'KO',
'message': 'Authorization pending'
}
+ Response 200 (application/json)
+ Body
{
'result': 'KO',
'message': 'Slow down'
}
+ Response 200 (application/json)
+ Body
{
'result': 'OK',
'access_token': ACCESS_TOKEN
}
# Group Calendar
Simkl provides separate JSON data calendar files that can be used to display the "Upcoming", "Next", "Schedule" or "Calendar" sections in your app or within show details cards.
The calendar files are generated every 6 hours and are cached on a CDN for 5 hours *(you can check the last-modified HTTP Headers for the file generation date)*.
The files URLs ignore all query strings, so **do not add** any additional parameters (such as **``?random=***``**).
<h3>How to use calendar data</h3>
You can use the calendar data to create lists of upcoming episodes, premieres (e.g. S01E01), or movies by combining it with your existing lists or using the user lists obtained from the [Sync](/#reference/sync) endpoints.
**Example:** When a user opens their watchlist, you can add the calendar data to show that the next episode will air in 3 days, without the need to re-sync the user's list. **Simply get fresh calendar files and cache them for 3-6 hours on the user's device.**
<h2>List of Calendar Data Files</h2>
<h3>Airing Next</h3>
Find out when the next episodes or movie releases are happening:
https://data.simkl.in/calendar/tv.json
https://data.simkl.in/calendar/anime.json
https://data.simkl.in/calendar/movie_release.json
**The calendar files contain episode airing dates (for TV, Anime) and theater release dates (for Movies) for the previous day as well as the next 33 days.**
<h3>Monthly Calendar Data Files</h3>
We update calendars for the past 12 months every 24 hours, and for the current month every 6 hours.
**Examples for January 2024:**
https://data.simkl.in/calendar/2024/1/tv.json
https://data.simkl.in/calendar/2024/1/anime.json
https://data.simkl.in/calendar/2024/1/movie_release.json
All calendar items have Simkl rank and ratings, [poster images](/#introduction/about-simkl-api/images), as well as SIMKL, TVDB, TMDB, IMDB, and MAL IDs where available.
# Group Checkin
Mobile apps can do checkin manually. If you are curretlty watching a movie or an episode you can simply do checkin from your phone or tablet and the episode will be automatically marked as watched in 15-40 minutes (based on the episode\movie lenth).
If you wish to instantly mark episode\movie as watched please use [Sync, Add to History method](/#reference/sync/add-to-history/check-into-an-item)
## Checkin [/checkin]
### Check into an item [GET]
<h4>🔒 Token Required</h4>
This should be tied to a user manual action. The item will be as watching on the site and if the time has elapsed it will switch to completed.
Pass as much data as possible into the item including `title`, `year` and `ids` fields so Simkl could detect the item better.
<h4>JSON POST DATA</h4>
Key|Type|Value
---|----|-----
item*|object|[episode or movie object](/#introduction/about-simkl-api/standard-media-objects).
<b>Note</b>: If there is checkin in progress, 409 code will be returned and response will contain an expires_at datetime when you will be able to ckeckin again.
+ Request (application/json)
+ Body
{
"movie": {
"title": "Guardians of the Galaxy",
"year": 2014,
"ids": {
"slug": "guardians-of-the-galaxy-2014",
"imdb": "tt2015381",
"tmdb": 118340
}
}
}
+ Response 200 (application/json)
+ Body
{
"movie": {
"title": "Guardians of the Galaxy",
"year": 2014,
"ids": {
"simkl": 212566,
"imdb": "tt2015381",
"tmdb": 118340
}
}
}
+ Request (application/json)
+ Body
{
"show": {
"title": "Breaking Bad",
"year": 2008,
"ids": {
"tvdb": 81189,
"imdb": "tt0903747"
},
"episode": {
"season": 2,
"number": 7
}
}
}
+ Response 200 (application/json)
+ Body
{
"show": {
"title": "Breaking Bad",
"year": 2008,
"ids": {
"tvdb": 81189,
"imdb": "tt0903747"
},
"episode": {
"season": 2,
"number": 7
}
}
}
+ Request
+ Body
{
"show": {
"netflix": 70236425
}
}
+ Response 200
+ Body
{
"show": {
"netflix": 70236425
}
}
+ Response 409
There is already a checkin in progress.
+ Body
{
"expires_at": "2015-05-10T20:11:25Z"
}
# Group Ratings
## Ratings API [/ratings]
### Get movie, tv show or anime rating [GET]
<h4>🔓 Token Not Required</h4>
Returns rating (between 0 and 10), rank (movie, tv, anime have their own rank), external ratings (IMDB, MAL), drop rate and if we have trailers for the movie or not(add /trailer parameter to the link and the best trailer will be opened).
Possible url parameters: [see Redirect method](/#reference/redirect/redirect-to-simkl-trailer-or-twitter/redirect).
+ Request
`https://api.simkl.com/ratings?simkl=10280&fields=rank,droprate,simkl,ext,has_trailer&client_id=***`
+ Header
+ Response 200 (application/json)
+ Body
{
"id":202806,
"link": "https://simkl.com/tv/10280/the-big-bang-theory",
"simkl":{
"rating":7.8,
"votes":1995
},
"rank":{
"type":"show",
"value":"1027"
},
"IMDB":{
"rating":8.1,
"votes":750606
},
"has_trailer":true
}
# Group Redirect
## Redirect to Simkl, trailer or Twitter [/redirect{?to,title,year,season,episode,client_id}]
In situations when you want to link directly to the Movie or TV show episode on Simkl from your Website or APP but don't know Simkl URL, you can use the Redirect API.
Redirect users directly to **Simkl** page, **Trailer** or to **Twitter** (to Share a Simkl link on Twitter with prefilled data).
### Use Cases
Here are some examples of the things you can build with the Redirect API:
- A browser extension to quickly link to Simkl based on page content.
- A website page linking directly to Simkl based on IMDB ID or TV Show name.
- Link to a trailer knowing only Movie name and year.
- Share an episode on Twitter from your browser extension.
- Get all Simkl IDs for your own API.
### Redirect [GET]
<h4>🔓 Token Not Required</h4>
<h4>🔒 client_id Not Required</h4>
Use this if you want to make a redirect to Simkl or (fast post) to Twitter using show's title or id. It will return "location" header.
The more parameters you'll pass, the more accurate redirect will be. Type `show` combine `tv` and `anime` types.
**Usage examples:**
https://api.simkl.com/redirect?to=Simkl&imdb=tt1520211
https://api.simkl.com/redirect?to=Simkl&imdb=https://www.imdb.com/title/tt1520211/
+ Parameters
+ to =`Simkl` (optional, string, `Simkl`) ... can be "Simkl" "trailer" or "twitter".
+ Values
+ `Simkl`
+ `trailer`
+ `twitter`
+ title (optional, string, `The Walking Dead`) ... TV show, anime, or movie title.
+ year (optional, integer, `2010`) ... release year.
+ season = `1` (optional, integer, `1`) ... if set, movies will be ignored. Anime do not have seasons.
+ episode (optional, integer, `4`) ... if set, movies will be ignored.
+ hulu (optional, integer, `752375`) ... hulu_id. All other parameters can be empty if this one specified.
+ netflix (optional, integer, `70210890`) ... Netflix `movieid`, this parameter is in beta and may not work.
+ mal (optional, integer, `4246`) ... MyAnimeList `id`.
+ tvdb (optional, integer, `153021, the-walking-dead`) ... TVDB ID. All other parameters can be empty if this one specified.
+ type (optional, integer, `show`) ... Required for better search by tmdb title field. Use 'show' to search both anime and tv. Use 'anime' to limit the search by title in anime. 'movie' is theatrical movie, not anime movie.
+ Values
+ `show`
+ `movie`
+ `tv`
+ `anime`
+ tmdb (optional, integer, `76757`) ... The Movie Database (TMDb) ID. To search TV Shows specify `type` parameter. All other parameters can be empty if this one specified.
+ imdb (optional, string, `tt1520211`) ... can be IMDB ID or full IMDB URL. All other parameters can be empty if this one specified.
+ Values
+ `tt1520211`
+ `http://www.imdb.com/title/tt1520211/`
+ anidb (optional, integer, `10846`) ... AniDB ID. All other parameters can be empty if this one specified.
+ crunchyroll (optional, integer, `656641`) ... Crunchyroll ID. You can pass episode ID or url ID(sword-art-online)
+ anilist (optional, integer, `21`) ... AniList ID
+ kitsu (optional, integer, `12`) ... Kitsu ID
+ livechart (optional, integer, `321`) ... LiveChart ID
+ anisearch (optional, integer, `2227`) ... aniSearch ID
+ animeplanet (optional, string, `one-piece`) ... Anime-Planet ID
+ traktslug (optional, string, `john-wick-chapter-4-2023`) ... Trakt slug
+ letterboxd (optional, string, `the-truman-show`) ... Letterboxd slug
+ client_id (string) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request
**Redirect to Simkl**, episode page example:
https://api.simkl.com/redirect?to=Simkl&title=The%20walking%20dead&year=2010&season=1&episode=4&type=show&tmdb=1402&client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 302
You will get "location" header (browser redirect) where the user should be redirected.
In this example user will be redirected to [Simkl: The Walking Dead S01E4](https://simkl.com/tv/2090/the-walking-dead/season-1/episode-4/)
+ Headers
location: //simkl.com/tv/2090/the-walking-dead/season-1/episode-4/
+ Body
+ Request
**Redirect to Simkl**, based on Hulu ID example:
https://api.simkl.com/redirect?to=Simkl&hulu=740489&client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 302
You will get "location" header (browser redirect) where the user should be redirected.
In this example user will be redirected to [Simkl: The Vampire Diaries S06E11](https://simkl.com/tv/15578/the-vampire-diaries/season-6/episode-11/)
+ Headers
location: //simkl.com/tv/15578/the-vampire-diaries/season-6/episode-11/
+ Body
+ Request
**Redirect to Simkl**, based on IMDB link example:
https://api.simkl.com/redirect?to=Simkl&imdb=http://www.imdb.com/title/tt1520211/&client_id=***
PS: Please use your `client_id`. You can specify IMDB ID `tt1520211` or full IMDB URL.
+ Body
+ Response 302
You will get "location" header (browser redirect) where the user should be redirected.
In this example user will be redirected to [Simkl: The Walking Dead](https://simkl.com/tv/2090/the-walking-dead)
+ Headers
location: //simkl.com/tv/2090/the-walking-dead
+ Body
+ Request
**Redirect to trailer** page example:
https://api.simkl.com/redirect?to=trailer&title=Guardians%20of%20the%20Galaxy&year=2014&client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 302
You will get "location" header (browser redirect) where the user should be redirected.
In this example user will be redirected to [Simkl: Guardians of the Galaxy (2014)](https://simkl.com/movies/212566/guardians-of-the-galaxy)
+ Headers
location: //simkl.com/movies/212566/guardians-of-the-galaxy
+ Body
+ Request
**Post to twitter** example:
https://api.simkl.com/redirect?to=twitter&title=The%20walking%20dead&year=2010&season=1&episode=4&client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 302
You will get "location" header (browser redirect) where the user should be redirected.
In this example user will be redirected to [twitter: Share a link with your followers](https://twitter.com/intent/tweet?text=The%20Walking%20Dead+1x04+%22Vatos%22&url=https%3A%2F%2Fsimkl.com%2Ftv%2F2090%2Fthe-walking-dead%2Fseason-1%2Fepisode-4%2F)
+ Headers
location: //twitter.com/intent/tweet?text=The Walking Dead+1x04+%22Vatos%22&url=https%3A%2F%2Fsimkl.com%2Ftv%2F2090%2Fthe-walking-dead%2Fseason-1%2Fepisode-4%2F
+ Body
## Mark as watched from your website [/redirect{?to,title,year,season,episode,client_id}]
Simple href link to mark something as watched from your website or app.
### Mark as watched [GET]
<h4>🔓 Token Not Required</h4>
<h4>🔒 client_id Required</h4>
You can use the same parameters as in Redirect with `to=watched`.
On first use, the user will be shown the Allow dialog to allow your app mark as watched in his profile and then redirected to the episode or movie with "**Marked as watched** notification".
Currently supports marking episodes in TV Shows and Anime. If you would like mark movies or add to plan to watch list, please let us know, we'll add the functionality.
HTML example of a button: https://codepen.io/masyk/pen/BaGLmNr
+ Parameters
+ to =`watched`
+ title (optional, string, `The Walking Dead`) ... TV show, anime, or movie title.
+ year (optional, integer, `2010`) ... release year.
+ season = `1` (optional, integer, `1`) ... if set, movies will be ignored. Anime do not have seasons.
+ episode (optional, integer, `4`) ... if set, movies will be ignored.
+ hulu (optional, integer, `752375`) ... hulu_id. All other parameters can be empty if this one specified.
+ netflix (optional, integer, `70210890`) ... Netflix `movieid`, this parameter is in beta and may not work.
+ mal (optional, integer, `4246`) ... MyAnimeList `id`.
+ tvdb (optional, integer, `153021, the-walking-dead`) ... TVDB ID. All other parameters can be empty if this one specified.
+ type (optional, integer, `show`) ... Required for tmdb, if is searching for a TV Show
+ Values
+ `show`
+ `movie`
+ tmdb (optional, integer, `76757`) ... The Movie Database (TMDb) ID. To search TV Shows specify `type` parameter. All other parameters can be empty if this one specified.
+ imdb (optional, string, `tt1520211`) ... can be IMDB ID or full IMDB URL. All other parameters can be empty if this one specified.
+ Values
+ `tt1520211`
+ `http://www.imdb.com/title/tt1520211/`
+ anidb (optional, integer, `10846`) ... AniDB ID. All other parameters can be empty if this one specified.
+ crunchyroll (optional, integer, `656641`) ... Crunchyroll ID. You can pass episode ID or url ID(sword-art-online)
+ anilist (optional, integer, `21`) ... AniList ID
+ kitsu (optional, integer, `12`) ... Kitsu ID
+ livechart (optional, integer, `321`) ... LiveChart ID
+ anisearch (optional, integer, `2227`) ... aniSearch ID
+ animeplanet (optional, integer, `one-piece`) ... Anime-Planet ID
+ client_id (string) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request
**Mark** The Walking Dead season 1 episode 4 **as watched** example:
https://api.simkl.com/redirect?to=watched&title=The%20walking%20dead&year=2010&season=1&episode=4&type=show&tmdb=1402&client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 302
User will be redirected to the episode page plus ?mark=watched&client_id=***.
In this example user will be redirected to [Simkl: The Walking Dead S01E4](https://simkl.com/tv/2090/the-walking-dead/season-1/episode-4/?mark=watched&client_id=***)
+ Headers
location: //simkl.com/tv/2090/the-walking-dead/season-1/episode-4/?marked=watched&client_id=***
+ Body
# Group Search
## ID Lookup [/search/id{?imdb,client_id}]
### Get items by ID[GET]
<h4>🔓 Token Not Required</h4>
You can lookup items by their ID using this endpoint. Supports IMDB, TVDB, TMDB, AniDB, Hulu, Netflix, MAL, Crunchyroll ID. This method will respond with [`Standard Media Object`](/introduction/about-simkl-api/standard-media-objects).
`status` field values in response are:
`ended`,`tba`,`airing` for anime\tv and
`released`,`upcoming` for movies.
+ Parameters
+ simkl (optional, integer, `2090`) ... Simkl `id`.
+ hulu (optional, integer, `752375`) ... hulu_id. All other parameters can be empty if this one specified.
+ netflix (optional, integer, `70210890`) ... Netflix `movieid`, this parameter is in beta and may not work.
+ mal (optional, integer, `4246`) ... MyAnimeList `id`.
+ tvdb (optional, integer, `153021, the-walking-dead`) ... TVDB ID. All other parameters can be empty if this one specified.
+ type (optional, integer, `show`) ... Required for tmdb, if is searching for a TV Show
+ Values
+ `show`
+ `movie`
+ tmdb (optional, integer, `76757`) ... The Movie Database (TMDb) ID. All other parameters can be empty if this one specified. `type` parameter is required if you want to search for TV Shows
+ imdb (optional, string, `tt1972591`) ... can be IMDB ID or full IMDB URL. All other parameters can be empty if this one specified.
+ Values
+ `tt1972591`
+ `http://www.imdb.com/title/tt1972591/`
+ anidb (optional, integer, `10846`) ... AniDB ID. All other parameters can be empty if this one specified.
+ crunchyroll (optional, integer, `656641`) ... Crunchyroll ID. You can pass episode ID or url ID(sword-art-online)
+ anilist (optional, integer, `21`) ... AniList ID
+ kitsu (optional, integer, `12`) ... Kitsu ID
+ livechart (optional, integer, `321`) ... LiveChart ID
+ anisearch (optional, integer, `2227`) ... aniSearch ID
+ animeplanet (optional, integer, `one-piece`) ... Anime-Planet ID
+ type (optional, string) ... Only used when sending tmdb.
+ Values
+ `show`
+ `movie`
+ title (optional, string, `The Walking Dead`) ... TV show, anime, or movie title. If this title has more then 1 item then null will be returned, add more fields to narrow down the search to 1 item(such as type,year etc.)
+ year (optional, integer, `2010`) ... release year.
+ client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request
**Search by ID**, IMDB example:
https://api.simkl.com/search/id?imdb=tt1972591&client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 200 (application/json)
+ Body
[
{
"type": "movie",
"title": "King Arthur: Legend of the Sword",
"poster": "28/2893788382afb90ce",
"year": 2017,
"status": "released",
"ids": {
"simkl": 388306,
"slug": "king-arthur-legend-of-the-sword"
}
},{
"type": "tv",
"title": "The Walking Dead",
"poster": "16\/16913426086fc13",
"year": 2010,
"status": "ended",
"ids": {
"simkl": 2090,
"slug": "the-walking-dead"
},
"total_episodes": 177
}
]
## Text [/search/{type}{?q,client_id}]
### Get items based on text query[GET]
<h4>📄 Pagination 🔓 Token Not Required ✨ Full Info</h4>
Search items by title, sorted by relevance (what people search most). This method will respond with [`Standard Media Object`](/introduction/about-simkl-api/standard-media-objects) + additional fields if `extended` parameter passed.
For `movies` or `anime` with movie type, tmdb id points to the movies section on TMDB site, otherwise to the TV section
Items with `endpoint_type = anime` has additional anime `type` key, see possible values for the `anime_type` key in [`Standard Media Object`](/introduction/about-simkl-api/standard-media-objects),
Page limit is 20, max items per page is 50.
+ Parameters
+ type (required, string, `movie`) ... Search type.
+ Values
+ `tv`
+ `anime`
+ `movie`
+ q (required, string, `john wick`) ... A search term or a URL pointing to media. <br><br>When using URLs, **`type`** can be any, not required to be correct one. <br><br>Type is required for text keywords.
+ Example: `john wick`
+ Example: `john wick 2014`
+ Example: `https://www.imdb.com/title/tt2911666/`
+ Example: `https://letterboxd.com/film/john-wick/`
+ client_id (optional, string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request
**Search for text**, movie title, john wick example: