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:support@simkl.com" 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 support@simkl.com 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 returning 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 preferred 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-01T09:10:11Z",
"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 length).
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
The **Simkl Ratings API** allows you to retrieve Simkl average rating information (0–10), ranks, external ratings (e.g. IMDB, MAL), drop rates, and trailer availability for movies, TV shows, and anime on Simkl.
## Ratings by ID [/ratings{?simkl,fields,client_id}]
### Get movie, TV show, or anime rating [GET]
<h4>🔓 Token Not Required</h4>
> You only need to supply a valid `client_id` obtained from your [App Settings](https://simkl.com/settings/developer/).
Use this endpoint to retrieve rating information by providing a **Simkl ID**. You can request additional fields, such as external ratings (IMDB, MAL), trailer availability, etc.
+ Parameters
+ simkl (optional, integer, `10280`) ...
- The unique Simkl ID of the item (movie, TV show, or anime).
- Example: `simkl=10280`
- If omitted, the API might not return any data unless another valid ID parameter is provided.
+ fields (optional, string, `rank,droprate,simkl,ext,has_trailer,reactions,year`) ...
- A comma-separated list of additional fields to include in the response.
- `simkl` – returns the Simkl rating and votes.
- `ext` – includes external ratings such as IMDB or MAL if available.
- `rank` – returns the rank within the Simkl service for that media type (movie, tv, anime).
- `status` – includes the release status of the item.
- `year` – includes the year of release.
- `reactions` – includes reaction data if available.
- `has_trailer` – indicates if the movie/TV show/anime has a trailer.
- Example: `fields=rank,droprate,simkl,ext,has_trailer,reactions,year`
+ Values
+ `simkl`
+ `ext`
+ `rank`
+ `status`
+ `year`
+ `reactions`
+ `has_trailer`
+ 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/).
Returns ratings (0-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 IDs: [see Redirect method](/#reference/redirect/redirect-to-simkl-trailer-or-twitter/redirect).
+ Parameters
+ client_id (string) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request
`https://api.simkl.com/ratings?simkl=10280&fields=rank,droprate,simkl,ext,has_trailer,reactions,year&client_id=***`
+ Header
+ Response 200 (application/json)
+ Body
{
"id": 10280,
"link": "https://simkl.com/tv/10280/the-big-bang-theory",
"simkl": {
"rating": 7.9,
"votes": 3378
},
"release_year": "2007",
"reactions": {
"total": 89,
"reviews": 5,
"comments": 18,
"positive": 4,
"negative": 0,
"neutral": 1
},
"rank": {
"type": "show",
"value": "1071"
},
"droprate": "3.2%",
"IMDB": {
"rating": 8.1,
"votes": 895026
},
"has_trailer": true
}
## Ratings by Watchlist [/ratings{/type}{?user_watchlist,fields,client_id}]
### Get ratings for the watchlist's items [GET]
<h4>🔓 Token Required</h4>
#### When to use it:
Use this endpoint when you need updated ratings or release status for **items in a user’s watchlist**. For example, cached data from `/sync/` can change over time if show airing statuses or movie release information are updated.
#### What you can fetch:
- Ratings and statuses for movies, TV shows, and anime in a user’s watchlist.
- Filter by list type (`all`,`watching`, `plantowatch`, `completed`, `dropped`, `hold`).
- Current release status for each item (e.g., ongoing, released, ended).
It is highly recommended to cache data for ended TV/anime shows and released movies (or items in the Completed list) for longer periods, as their average ratings and statuses rarely change.
> possible `fields` values: `simkl,link,ext,rank,release_status,year`
###### `release_status` Response:
Below is a table of possible `release_status` values by media type:
| Type | Release Status | Meaning |
|:-----------:|:-----------------------------------------|:-----------------------------------------------------------|
| **`movie`** | **`upcoming`, `rumored`, `planned`, `in production`, `post production`,`cancelled`** | Various states indicating the movie is not yet fully released or has been cancelled. |
| | **`released`** | The movie is already out. |
|
| **`tv`** | **`upcoming`, `planned`, `in production`, `cancelled`** | The series is not yet released. |
| | **`returning series`** | The series is ongoing, with more episodes/seasons planned. |
| | **`ended`** | The series has finished; no new episodes will be released. |
|
| **`anime`** | **`upcoming`, `rumored` `planned`, `in production`, `post production`,`cancelled`** | The anime is not yet released.
| | **`ongoing`** | The anime is actively airing or has new episodes planned. |
| | **`ended`** | The anime has concluded; no new episodes are planned. |
+ Parameters
+ type (optional, string, `anime`)
+ Values
+ `tv`
+ `anime`
+ `movies`
+ user_watchlist = `all` (string,`watching,plantowatch`)
+ Values
+ `all`
+ `watching`
+ `plantowatch`
+ `completed`
+ `dropped`
+ `hold`
+ fields (optional, string, `link,simkl,ext,rank,release_status,year`) ...
- A comma-separated list of additional fields to include in the response.
- `simkl` – returns the Simkl rating and votes.
- `ext` – includes external ratings such as IMDB or MAL if available.
- `rank` – returns the rank within the Simkl service for that media type (movie, tv, anime).
- `release_status` – includes the release status of the item.
- `year` – includes the year of release.
- Example: `fields=rank,droprate,simkl,ext,year`
+ Values
+ `simkl`
+ `ext`
+ `rank`
+ `release_status`
+ `year`
+ `reactions`
+ `has_trailer`
+ client_id (string) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request
`https://api.simkl.com/ratings/anime/?user_watchlist=watching,plantowatch&fields=link,ext,simkl,rank,release_status,year&client_id=***`
+ Header
+ Response 200 (application/json)
+ Body
[
{
"id": 268470,
"type": "movie",
"link": "https:\/\/simkl.com\/movies\/268470\/tinker-bell-and-the-pirate-fairy",
"release_status": "released",
"release_year": 2014,
"rank": 10628,
"simkl": {
"rating": 7.1,
"votes": 151,
"droprate": "1%"
},
"imdb": {
"rating": 6.6,
"votes": 15119
}
},
{
"id": 2331788,
"type": "anime",
"link": "https:\/\/simkl.com\/anime\/2331788\/kamonohashi-ron-no-kindan-suiri-2nd-season",
"release_status": "ongoing",
"release_year": 2024,
"rank": 1561,
"simkl": {
"rating": 7,
"votes": 19,
"droprate": "3.9%"
},
"mal": {
"rating": 7.6,
"votes": 4132,
"rank": 1693
}
}
]
# 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 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:
https://api.simkl.com/search/movie?q=john%20wick&page=1&limit=10&client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 200 (application/json)
+ Headers
Content-Type:application/json
X-Pagination-Page:1
X-Pagination-Limit:10
X-Pagination-Page-Count:20
X-Pagination-Item-Count:50
+ Body
[
{
"title":"John Wick: Chapter 2",
"year":2017,
"poster": "54\/5465988836c0aaa33",
"endpoint_type": "movies",
"ids":{
"simkl_id":471618,
"slug":"john-wick-chapter-2",
"tmdb":"324552"
}
},
{
"title":"John Wick",
"endpoint_type": "movies",
"year":2014,
"poster": "28\/2893788382afb90ce",
"ids":{
"simkl_id":342994,
"slug":"john-wick",
"tmdb":"245891"
}
},
{
"title":"John Wick: Chapter 3",
"endpoint_type": "movies",
"year":2019,
"poster": "57\/5747702654de3d19d",
"ids":{
"simkl_id":687232,
"slug":"john-wick-chapter-3"
}
}
]
+ Request
**Search for text with full info**, movie title, john wick example:
https://api.simkl.com/search/movie?q=john%20wick&page=1&limit=10&extended=full&client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 200 (application/json)
+ Headers
Content-Type:application/json
X-Pagination-Page:1
X-Pagination-Limit:10
X-Pagination-Page-Count:20
X-Pagination-Item-Count:50
+ Body
[{
"title": "John Wick: Chapter 2",
"endpoint_type": "movies",
"year": 2017,
"poster": "50\/501682403c298b56c",
"url": "\/movies\/471618\/john-wick-chapter-2",
"rank": 2326,
"ids": {
"simkl_id": 471618,
"slug": "john-wick-chapter-2",
"tmdb":"324552"
},
"ratings": {
"simkl": {
"rating": 7.7,
"votes": 360
},
"imdb": {
"rating": 7.5,
"votes": 249581
}
}
}, {
"title": "John Wick",
"endpoint_type": "movies",
"year": 2014,
"poster": "28\/2893788382afb90ce",
"url": "\/movies\/342994\/john-wick",
"rank": 3998,
"ids": {
"simkl_id": 342994,
"slug": "john-wick",
"tmdb":"245891"
},
"ratings": {
"simkl": {
"rating": 7.7,
"votes": 503
},
"imdb": {
"rating": 7.3,
"votes": 405845
}
}
}, {
"title": "John Wick: Chapter 3",
"endpoint_type": "movies",
"year": 2019,
"poster": "57\/5747702654de3d19d",
"url": "\/movies\/687232\/john-wick-chapter-3",
"rank": null,
"ids": {
"simkl_id": 687232,
"slug": "john-wick-chapter-3"
},
"ratings": {
"simkl": {
"rating": 8.5,
"votes": 2
}
}
}]
+ Request
**Search by url**, imdb anime Attack on Titan example in "movie" endpoint:
https://api.simkl.com/search/movie?q=https://www.imdb.com/title/tt2560140/&page=1&limit=10&extended=full&client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 200 (application/json)
+ Headers
Content-Type:application/json
X-Pagination-Page:1
X-Pagination-Limit:10
X-Pagination-Page-Count:20
X-Pagination-Item-Count:50
+ Body
[
{
"title": "Shingeki no Kyojin",
"title_en": "Attack on Titan (S1)",
"title_romaji": "Shingeki no Kyojin",
"year": 2013,
"endpoint_type": "anime",
"type": "tv",
"poster": "23\/23563e7856a42e5",
"all_titles": [
"Shingeki no Kyojin",
"Attack on Titan",
"\u8fdb\u51fb\u7684\u5de8\u4eba",
"Advancing Giants",
"Shingeki no Kyojin TV",
"Shingeki no Kyojin S1",
"AoT",
"SnK",
"shingeki",
"AoT TV"
],
"url": "\/anime\/39687\/shingeki-no-kyojin",
"ep_count": 25,
"rank": 109,
"status": "ended",
"ratings": {
"simkl": {
"rating": 8.7,
"votes": 7715
},
"mal": {
"rating": 8.6,
"votes": 2877607,
"rank": 117
}
},
"ids": {
"simkl_id": 39687,
"slug": "shingeki-no-kyojin"
}
}
]
## File [/search/file]
### Find show, anime or movie by file[POST]
<h4>🔓 Token Not Required</h4>
Use it if you have a filename and want to get simkl_id based on it. Right now TV Shows and Anime files can be recognized the best. Movies are harder to recognize without using the hash.
You can search by filename or by full folder+filename (see request examples).
This method will respond with [`Standard Media Object`](/introduction/about-simkl-api/standard-media-objects) + some new fields.
`multipart` = we have 2+ episodes in one filename, use `part` parameter to get necessary episode.
<h4>POSSIBLE JSON RESPONSE DATA</h4>
Key|Value|Description
---|----|-----
type|`episode`| this is an episode of a TV Show or Anime
type|`movie`| this is movie
episode: multipart |`false`| not multipart
episode: multipart |`0`| no more episodes left
episode: multipart |`1`| you can get info on one more episode after this one in this filename
+ Request (application/json)
This is an example with a file that has 2 episodes at the same time, and we're trying to get information about the first episode (part 1 of 2).
+ Headers
simkl-api-key: [client_id]
+ Attributes
+ file: `Were.The.Fugawis.S01E01E02.WS.DSR.x264-NY2.mkv` (required, string) - Trying to find this file in our DB
+ part: `1` (optional, number) - Some filenames consist of 2 or more parts. If you want to get info about second part for example you can pass `2` to this parameter
+ hash (optional, string) - [IN_DEV]
+ Response 200 (application/json)
+ Body
{
"type": "episode",
"show": {
"title": "We're the Fugawis",
"year": 2013,
"ids": {
"simkl": 43283,
"zap2it": "EP01767728",
"tvdb": 272581
}
},
"episode": {
"title": "The Fug Life",
"season": 1,
"episode": 1,
"multipart": 1,
"ids": {
"simkl": 967216
}
}
}
+ Request (application/json)
This is an example with a full file location including folders.
+ Header
simkl-api-key: [client_id]
+ Attributes
+ file: `/series/The Office/Season 4/The Office [401] Fun Run.avi` (required, string) - You can use folders in the file request as well
+ Response 200 (application/json)
+ Body
{
"type": "episode",
"show": {
"title": "The Office (US)",
"year": 2005,
"ids": {
"simkl": 2753,
"imdb": "tt0386676",
"zap2it": "SH00726133",
"netflix": "70136120",
"tvdb": "73244"
}
},
"episode": {
"title": "Fun Run (1)",
"season": 4,
"episode": 1,
"multipart": false,
"ids": {
"simkl": 343712
}
}
}
## Random [/search/random{?service,type,genre,rating_from,rating_to,rank_limi,year_from,year_to,limit,client_id}]
### Find random show, anime or movie [POST]
<h4>🔓 Token Optional</h4>
Use it if you want to find random item based on your filters. If Token is passed, wacthed items will be excluded.
### Use Cases
Here are some examples of the things you can build with the Random Search API:
- Find random Netflix TV Show, Anime or Movie to watch
- Find random TV Show, Anime or Movie in Simkl database
### Requirements
"Powered by SIMKL" with a link to https://simkl.com is required on the web page or inside your app where this functionality is used.
+ Parameters
+ service = `simkl` (optional, string) ... Finds random TV Show, Anime or Movie.
+ Values
+ `netflix`
+ `simkl`
+ type (optional, integer, `tv`) ...
+ Values
+ `tv`
+ `anime`
+ `movie`
+ genre = (optional, string, `comedy`) ... TV Shows, Anime and Movies have their own genres. <br><br><b>Movies</b>: <br>action, adventure, animation, comedy, crime, documentary, drama, erotica, family, fantasy, foreign, history, horror, music, mystery, romance, science-fiction, thriller, tv-movie, war, western<br><b>TV:</b><br>action, adventure, animation, awards-show, children, comedy, crime, documentary, drama, erotica, family, fantasy, food, game-show, history, home-and-garden, horror, indie, korean-drama, martial-arts, mini-series, musical, mystery, news, podcast, reality, romance, science-fiction, soap, special-interest, sport, suspense, talk-show, thriller, travel, war, western<br><b>Anime:</b><br>action, adventure, cars, comedy, dementia, demons, drama, ecchi, fantasy, game, harem, historical, horror, josei, kids, magic, martial-arts, mecha, military, music, mystery, parody, police, psychological, romance, samurai, school, sci-fi, seinen, shoujo, shoujo-ai, shounen, shounen-ai, slice-of-life, space, sports, super-power, supernatural, thriller, vampire, yaoi, yuri
+ rating_from = `1` (optional, integer, `5`) ... max value is 10. Random search for TV Shows and Movies will be performed using IMDB ratings. Anime are based on MAL ratings.
+ rating_to (optional, integer, `10`)
+ rank_limit (optional, integer, `2000`) ... maximum rank allowed
+ year_from (optional, integer, `2004`) ... First released movie starts from 1920.
+ year_to (optional, integer, `2010`)
+ limit (optional, integer, `10`) ... if >0 specified it returns 2 dimensional array with multiple results
+ client_id (required, integer, `***`) ... If using [POST] with OAuth, it can be set in headers. If using without OAuth it's required.
+ Request
**Netflix** random example:
https://api.simkl.com/search/random/netflix/?rating_from=5&rating_to=10&year_from=2008&year_to=2015&genre=science-fiction&client_id=***
PS: Please use your `client_id`
+ Body
+ Response 302
EDIT HERE
+ Body
+ Request (application/json)
**Simkl** random example:
https://api.simkl.com/search/random/?rating_from=5&rating_to=10&year_from=2008&year_to=2015&genre=science-fiction&client_id=***
+ Header
Authorization: Bearer [token]
+ Response 200 (application/json)
+ Body
{
"id": 179868
"url": "https://simkl.com/movies/179868/terminator-genisys"
}
# Group TV
## Summary [/tv/{id}{?client_id}]
### Get detail info about the TV Show [GET]
<h4>🔓 Token Not Required ✨ Full Info</h4>
Returns a single detail info of the tv show.
The `status` field can have these values `ended`,`tba`,`airing`
+ Parameters
+ id (required, string, `tt0944947`) ... Simkl ID or IMDB ID.
+ client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request
**Short info**, IMDB example:
https://api.simkl.com/tv/tt0944947?client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 200 (application/json)
+ Body
{
"title": "Game of Thrones",
"year": 2011,
"type": "show",
"ids": {
"simkl": 17465,
"slug": "game-of-thrones"
}
}
+ Request
**Full info**, IMDB example:
https://api.simkl.com/tv/tt0944947?extended=full&client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 200 (application/json)
+ Body
{
"title": "Game of Thrones",
"year": 2011,
"type": "show",
"ids": {
"simkl": 17465,
"slug": "game-of-thrones",
"tvdb": "121361",
"imdb": "tt0944947",
"zap2it": "EP01389809"
},
"rank": 6,
"poster": "57\/5742576cd8f59fcb0",
"fanart": "65\/651708e80d87bb93",
"first_aired": "2011-04-18T01:00:00Z",
"airs": {
"day": "Sunday",
"time": "09:00 PM",
"timezone": "America\/New_York"
},
"runtime": 55,
"certification": "TV-MA",
"overview": "Seven noble families fight for control of the mythical land of Westeros. Friction between the houses leads to full-scale war. All while a very ancient evil awakens in the farthest north. Amidst the war, a neglected military order of misfits, the Night's Watch, is all that stands between the realms of men and the icy horrors beyond.",
"genres": ["Drama", "Fantasy", "Adventure"],
"country": "US",
"total_episodes": 67,
"status": "airing",
"network": "HBO",
"ratings": {
"simkl": {
"rating": 9.1,
"votes": 1270
},
"imdb": {
"rating": 9.5,
"votes": 1234933
}
},
"trailers": null
}
## Episodes [/tv/episodes/{id}{?client_id}]
### Get TV Show episodes [GET]
<h4>🔓 Token Not Required ✨ Full Info</h4>
Returns an array of all episodes of the TV Show
+ Parameters
+ id (required, integer) ... simkl id of the series
+ client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request
https://api.simkl.com/tv/episodes/2090?client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 200 (application/json)
+ Body
[{
"title": "Days Gone Bye",
"description": "Rick searches for his family after emerging from a coma into a world terrorized by the walking dead. Morgan and Duane, whom he meets along the way, help teach Rick the new rules for survival.",
"season": 1,
"episode": 1,
"type": "episode",
"img": "33\/33039065126ec2470",
"date": "2010-10-31T00:00:00-05:00",
"aired": true,
"ids": {
"simkl_id": 310766
}
}, {
"title": "Guts",
"description": "Rick unknowingly causes a group of survivors to be trapped by walkers. The group dynamic devolves from accusations to violence, as Rick must confront an enemy far more dangerous than the undead.",
"season": 1,
"episode": 2,
"type": "episode",
"img": "33\/3303806cc83f0ab83",
"date": "2010-11-07T00:00:00-05:00",
"aired": true,
"ids": {
"simkl_id": 310768
}
}, {
"title": "Behind The Dead (100 Episodes Special)",
"description": "Andrew Lincoln, Norman Reedus, and the rest of the cast and crew reflect on the history and celebrate reaching the 100th episode of The Walking Dead.",
"type": "special",
"img": "62\/6243336c0ad8db221",
"date": "2017-10-19T00:00:00-05:00",
"aired": false,
"ids": {
"simkl_id": 2527432
}
}]
## Trending [/tv/trending/{interval}{?client_id}]
### Get trending TV series [GET]
<h4>🔓 Token Not Required ✨ Full Info (Discover)</h4>
You can use any filters from the [Best](https://simkl.com/tv/best-anime/most-watched/) site section.
Select any filter\slider and copy it from the URL to this API endpoint.
This endpoint's default url filters are `?wltime=today&langs=en&subtype=-t_documentary,-t_youtube,-t_entertainment`
+ Parameters
+ interval = `today` (optional, string, `week`) ... Filter within the time period
+ Values
+ `today`
+ `week`
+ `month`
+ client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request
https://api.simkl.com/tv/trending/?extended=overview,metadata,tmdb,genres,trailer&client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 200 (application/json)
+ Body
[
{
"title": "Bluey",
"url": "\/tv\/922016\/bluey",
"poster": "73\/731473004195ba690",
"fanart": "76\/7674468ee5d6bd79b",
"ids": {
"simkl_id": 922016,
"slug": "bluey",
"tmdb": "82728"
},
"release_date": "10\/01\/2018",
"rank": 1,
"drop_rate": "7.1%",
"watched": 320,
"plan_to_watch": 57,
"ratings": {
"simkl": {
"rating": 6.65,
"votes": 23
},
"imdb": {
"rating": 9.6,
"votes": 10966
}
},
"country": "au",
"runtime": "7m",
"status": "ongoing",
"total_episodes": 155,
"network": "ABC Kids",
"metadata": "2018 - \u2022 ABC Kids \u2022 155 episodes",
"overview": "Bluey is an inexhaustible six year-old Blue Heeler dog, who loves to play and turns everyday family life into extraordinary adventures, developing her imagination as well as her mental, physical and emotional resilience.",
"genres": ["Animation", "Children", "Comedy", "Family"],
"trailer": "3pKDcQTY98E"
}, {
"title": "The Chosen",
"url": "\/tv\/995148\/the-chosen",
"poster": "96\/96387344b88c0a170",
"fanart": "90\/902468623a9ca1a0e",
"ids": {
"simkl_id": 995148,
"slug": "the-chosen",
"tmdb": "85077"
},
"release_date": "09\/21\/2017",
"rank": 16,
"drop_rate": "16.1%",
"watched": 192,
"plan_to_watch": 104,
"ratings": {
"simkl": {
"rating": 7.26,
"votes": 23
},
"imdb": {
"rating": 9.3,
"votes": 30133
}
},
"country": "us",
"runtime": "55m",
"status": "ongoing",
"total_episodes": 25,
"network": "Angel.com",
"metadata": "2017 - \u2022 Angel.com \u2022 25 episodes",
"overview": "A charismatic fisherman drowning in debt. A troubled woman wrestling with real demons. A young tax collector ostracized by society. A religious leader questioning his faith tradition.",
"genres": ["Drama", "Family", "History"],
"trailer": "K1-FoFj8Jbo"
}
]
## Genres [/tv/genres/{genre}/{type}/{country}/{network}/{year}/{sort}{?client_id}]
### Get items filtered by genre, years etc... [GET]
<h4>📄 Pagination 🔓 Token Not Required</h4>
Returns an array of ([Standard Media Object](#introduction/about-simkl-api/standard-media-objects))
This endpoint accepts all parameters from the https://simkl.com/tv/all/, select the necessary filters and copy parameters
from the url.
Genres API duplicates the urls of the Genres on the website so create a filter on the website and add it to genres API.
+ Parameters
+ genre = all (optional, string, `drama`)
+ type = tv-shows (optional, string, `documentaries`) ... Type of the series.
+ country = us (optional, string, `gb`) ... where the series were released
+ network = all-networks (optional, string, `netflix`) ... filter by network or production studio
+ year = 2010s (optional, string, `this-week`)
+ sort = rank (optional, string, `popular-this-month`)
+ client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request
Simple query<br>
https://api.simkl.com/tv/genres/drama/2016?client_id=***
Query with all parameters<br>
https://api.simkl.com/tv/genres/all/all-types/all-countries/hbo/all-years/popular-today?client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 200 (application/json)
+ Body
[{
"title": "Dirty John",
"year": 2018,
"date":"2018-11-09T00:00:00-05:00",
"url": "\/tv\/877196\/dirty-john",
"poster": "73\/73773541253a438ce",
"ids": {
"simkl_id": 877196,
"slug": "dirty-john"
},
"rank": null,
"ratings": {
"simkl": {
"rating": 8,
"votes": 1
},
"imdb": {
"rating": 7.2,
"votes": 33
}
}
}, {
"title": "Holiday Gingerbread Showdown",
"year": 2018,
"date":"2018-11-07T00:00:00-05:00",
"url": "\/tv\/962792\/holiday-gingerbread-showdown",
"poster": "74\/74691884f61c810cd",
"ids": {
"simkl_id": 962792,
"slug": "holiday-gingerbread-showdown"
},
"rank": null,
"ratings": {
"simkl": {
"rating": 0,
"votes": 0
},
"imdb": {
"rating": 0,
"votes": 0
}
}
}]
## Premieres [/tv/premieres/{param}{?type}{?client_id}]
### Get latest premieres [GET]
<h4>📄 Pagination 🔓 Token Not Required</h4>
Returns an array of ([Standard Media Object](#introduction/about-simkl-api/standard-media-objects))
+ Parameters
+ param (required, string) ...
+ Values
+ `new`
+ `soon`
+ type (optional, string, `all`) ... show only results with this type
+ Values
+ `all`
+ `entertainment`
+ `documentaries`
+ `animation-filter`
+ client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request
https://api.simkl.com/tv/premieres/new?client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 200 (application/json)
+ Body
[{
"title": "Dirty John",
"year": 2018,
"date":"2018-11-09T00:00:00-05:00",
"url": "\/tv\/877196\/dirty-john",
"poster": "73\/73773541253a438ce",
"ids": {
"simkl_id": 877196,
"slug": "dirty-john"
},
"rank": null,
"ratings": {
"simkl": {
"rating": 8,
"votes": 1
},
"imdb": {
"rating": 7.2,
"votes": 33
}
}
}, {
"title": "Holiday Gingerbread Showdown",
"year": 2018,
"date":"2018-11-07T00:00:00-05:00",
"url": "\/tv\/962792\/holiday-gingerbread-showdown",
"poster": "74\/74691884f61c810cd",
"ids": {
"simkl_id": 962792,
"slug": "holiday-gingerbread-showdown"
},
"rank": null,
"ratings": {
"simkl": {
"rating": 0,
"votes": 0
},
"imdb": {
"rating": 0,
"votes": 0
}
}
}]
## Airing [/tv/airing?{date}{?sort}{?client_id}]
### Get Airing TV Shows [GET]
<h4>🔓 Token Not Required</h4>
Returns airing TV Shows ([Standard Media Object](#introduction/about-simkl-api/standard-media-objects))
+ Parameters
+ date (optional, string, `today`) ... only data within this date
+ Values
+ `today`
+ `tomorrow`
+ `22-08-2022`
+ sort (optional, string, `time`) ... sort the results by the specified option
+ Values
+ `time`
+ `rank`
+ `popularity`
+ client_id (required, string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request
https://api.simkl.com/tv/airing?client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 200 (application/json)
+ Body
[{
"title": "High School Musical: The Musical: The Series",
"year": 2022,
"date": "2022-09-14T02:00:00-05:00",
"poster": "89\/8992886023a82f72e",
"rank": 5869,
"url": "\/tv\/1044024\/high-school-musical-the-musical-the-series",
"ids": {
"simkl_id": 1044024,
"slug": "high-school-musical-the-musical-the-series"
},
"episode": {
"season": 3,
"episode": 8,
"url": "\/tv\/1044024\/high-school-musical-the-musical-the-series\/season-3\/episode-8"
}
}, {
"title": "She-Hulk: Attorney at Law",
"year": 2022,
"date": "2022-09-14T03:00:00-05:00",
"poster": "95\/95314368aad7d4e2e",
"rank": null,
"url": "\/tv\/1155406\/she-hulk-attorney-at-law",
"ids": {
"simkl_id": 1155406,
"slug": "she-hulk-attorney-at-law"
},
"episode": {
"season": 1,
"episode": 5,
"url": "\/tv\/1155406\/she-hulk-attorney-at-law\/season-1\/episode-5"
}
}]
## Best [/tv/best/{filter}{?type}{?client_id}]
### Get best of all TV Shows [GET]
<h4>🔓 Token Not Required</h4>
Returns an array of customized ([Standard Media Object](#introduction/about-simkl-api/standard-media-objects))
+ Parameters
+ filter (required, string) ... <b>watched</b> and <b>voted</b> adds additional key in response with the same name
+ Values
+ `year`
+ `month`
+ `all`
+ `voted`
+ `watched`
+ type (optional, string, `series`) ... secondary filter
+ Values
+ `series`
+ `documentary`
+ `entertainment`
+ `animation`
+ client_id (required, string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request
https://api.simkl.com/anime/best/watched?client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 200 (application/json)
+ Body
[{
"title": "Chilling Adventures of Sabrina",
"year": 2018,
"poster": "72\/7241248bcd26cf4ed",
"url": "\/tv\/751254\/chilling-adventures-of-sabrina",
"watched": 1656,
"ids": {
"simkl_id": 751254,
"slug": "chilling-adventures-of-sabrina"
},
"ratings": {
"simkl": {
"rating": 7.4,
"votes": 72
},
"imdb": {
"rating": 7.9,
"votes": 25391
}
}
}, {
"title": "Marvel's Daredevil",
"year": 2015,
"poster": "27\/2769324e0ed6160e0",
"url": "\/tv\/51884\/marvels-daredevil",
"watched": 1653,
"ids": {
"simkl_id": 51884,
"slug": "marvels-daredevil"
},
"ratings": {
"simkl": {
"rating": 8.3,
"votes": 815
},
"imdb": {
"rating": 8.7,
"votes": 311910
}
}
}]
# Group Anime
## Summary [/anime/{id}{?client_id}]
### Get detail info about the Anime [GET]
<h4>🔓 Token Not Required ✨ Full Info</h4>
Returns a single detail info of the anime. Same as `/tv/summary` endpoint + added `anime_type`,`en_title` fields, possible values are `tv`,`special`,`ova`, `movie`,`music video`,`ona`.
+ Parameters
+ id (required, string, `40398`) ... Simkl ID or IMDB ID.
+ client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request
**Short info**, SIMKL ID example:
https://api.simkl.com/anime/40398?client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 200 (application/json)
+ Body
{
"title": "Hunter x Hunter",
"year": 2011,
"type": "anime",
"ids": {
"simkl": 40398,
"slug": "hunter-x-hunter"
}
}
+ Request
**Full info**, SIMKL ID example:
https://api.simkl.com/anime/40398?extended=full&client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 200 (application/json)
+ Body
{
"title": "Hunter x Hunter",
"year": 2011,
"type": "anime",
"ids": {
"simkl": 40398,
"slug": "hunter-x-hunter",
"anidb": "8550",
"ann": "13262",
"mal": "11061",
"anfo": "4947",
"wikien": "Hunter_x_hunter",
"allcin": "340525",
"imdb": "tt2098220",
"offjp": "https:\/\/twitter.com\/hunter_anime",
"crunchyroll": "hunter-x-hunter",
"anilist": "11061",
"kitsu": "6448",
"livechart": "317",
"anisearch": "7223",
"animeplanet": "hunter-x-hunter-2011"
},
"en_title": null,
"rank": 7,
"poster": "83\/83975f751784587",
"fanart": "83\/839789583130112",
"first_aired": "2011-10-02T02:00:00Z",
"airs": {
"day": "Sunday",
"time": "11:00 AM",
"timezone": "Asia\/Tokyo"
},
"runtime": 25,
"certification": null,
"overview": "A remake of the original series with different staff and cast.<br><br>Gon is a youth who lives on Kujira Isle. His dream is to become a Hunter like his father, to search out lost treasures, artefacts, and mythical creatures.<br><br>Determined to become a professional Hunter willing to stake his life in challenging the unknown, he sets off on a journey and meets fellow Hunter wannabes Killua, Kurapika, and Leorio.",
"genres": ["Action", "Adventure", "Comedy"],
"country": "JP",
"total_episodes": 148,
"status": "ended",
"network": "NTV",
"anime_type": "tv",
"ratings": {
"simkl": {
"rating": 8.9,
"votes": 248
},
"imdb": {
"rating": 7.6,
"votes": 1077
},
"mal": {
"rating": 9.1,
"votes": 324100,
"rank": 7
}
},
"trailers": [{
"name":null,
"youtube":"t0xuqi2qvxY",
"size":720
}],
"users_recommendations":[{
"title": "Overlord",
"en_title": null,
"year": 2015,
"poster": "69\/69770748206def778",
"anime_type": "tv",
"users_percent": "34%",
"users_count": 23,
"ids": {
"simkl": 415932,
"slug": "overlord"
}
}, {
"title": "Tate no Yuusha no Nariagari",
"en_title": "The Rising of the Shield Hero",
"year": 2018,
"poster": "74\/74755663f6cfe2818",
"anime_type": "tv",
"users_percent": "7%",
"users_percent": 5,
"ids": {
"simkl": 695799,
"slug": "tate-no-yuusha-no-nariagari"
}
}, {
"title": "Isekai wa Smartphone to Tomo ni.",
"en_title": "In Another World with My Smartphone",
"year": 2017,
"poster": "56\/56612089b2d99025c",
"anime_type": "tv",
"users_percent": "7%",
"users_percent": 4,
"ids": {
"simkl": 670707,
"slug": "isekai-wa-smartphone-to-tomo-ni"
}
}]
}
## Episodes [/anime/episodes/{id}{?client_id}]
### Get Anime episodes [GET]
<h4>🔓 Token Not Required ✨ Full Info</h4>
Returns an array of all episodes of the Anime
+ Parameters
+ id (required, integer) ... simkl id of the anime
+ client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request
https://api.simkl.com/anime/episodes/39687?client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 200 (application/json)
+ Body
[{
"title": "To You, 2000 Years in the Future: The Fall of Zhiganshina (1)",
"description": null,
"episode": 1,
"type": "episode",
"aired": true,
"img": "26\/26148581d640c58b8",
"date": "2013-04-07T00:00:00+09:00",
"ids": {
"simkl_id": 958466
}
}, {
"title": "That Day: The Fall of Zhiganshina (2)",
"description": null,
"episode": 2,
"type": "episode",
"aired": true,
"img": "26\/2614860d56b63e7b6",
"date": "2013-04-14T00:00:00+09:00",
"ids": {
"simkl_id": 958465
}
}, {
"title": "Picture Drama 3",
"description": null,
"type": "special",
"aired": true,
"img": "68\/689124d248604d0d",
"date": "2013-09-18T00:00:00+09:00",
"ids": {
"simkl_id": 979612
}
}]
## Trending [/anime/trending/{interval}{?client_id}]
### Get trending anime series [GET]
<h4>🔓 Token Not Required ✨ Full Info (Discover)</h4>
You can use any filters from the [Best](https://simkl.com/anime/best-anime/most-watched/) site section.
Select any filter\slider and copy it from the URL to this API endpoint.
This endpoint's default url filters are `?wltime=today`
+ Parameters
+ interval = `today` (optional, string, `week`) ... Filter within the time period
+ Values
+ `today`
+ `week`
+ `month`
+ client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request
https://api.simkl.com/anime/trending/?extended=overview,metadata,tmdb,genres,trailer&client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 200 (application/json)
+ Body
[
{
"title": "Bleach: Sennen Kessen Hen",
"url": "\/anime\/1300367\/bleach-sennen-kessen-hen",
"poster": "97\/973878056c6c7a33d",
"fanart": "13\/1331024111faa4e05d",
"ids": {
"simkl_id": 1300367,
"slug": "bleach-sennen-kessen-hen",
"tmdb": "100645"
},
"release_date": "10\/10\/2022",
"rank": 1,
"drop_rate": "0.9%",
"watched": 1247,
"plan_to_watch": 1052,
"ratings": {
"simkl": {
"rating": 9.08,
"votes": 161
},
"mal": {
"rating": 9.2,
"votes": 111479
}
},
"country": "jp",
"runtime": "25m",
"status": "ended",
"anime_type": "tv",
"total_episodes": 13,
"network": "TV Tokyo",
"metadata": "2022 - 2022 \u2022 TV Tokyo \u2022 13 episodes",
"overview": "* Based on an adventure supernatural shounen manga by Kubo Taito.<br><br>The peace is suddenly broken when warning sirens blare through the Soul Society. Residents there are disappearing without a trace, and nobody knows who`s behind it. Meanwhile, a dark shadow is also extending itself toward Ichigo and his friends in Karakura Town...",
"genres": ["Action", "Adventure", "Comedy", "Fantasy", "Magic", "Shounen", "Super Power", "Supernatural"],
"trailer": "1sygUhb8Q2Y"
}, {
"title": "Kaguya-sama wa Kokurasetai: Ultra Romantic",
"url": "\/anime\/1462529\/kaguya-sama-wa-kokurasetai-ultra-romantic",
"poster": "11\/118961816276f04351",
"fanart": "12\/126537094d86545d2c",
"ids": {
"simkl_id": 1462529,
"slug": "kaguya-sama-wa-kokurasetai-ultra-romantic",
"tmdb": null
},
"release_date": "04\/08\/2022",
"rank": 4,
"drop_rate": "0.7%",
"watched": 2222,
"plan_to_watch": 768,
"ratings": {
"simkl": {
"rating": 9.07,
"votes": 466
},
"mal": {
"rating": 9.1,
"votes": 382462
}
},
"country": "",
"runtime": "25m",
"status": "ended",
"anime_type": "tv",
"total_episodes": 13,
"network": null,
"metadata": "2022 - 2022 \u2022 13 episodes",
"overview": "* Based on a romantic comedy seinen manga by Akasaka Aka.<br><br>Can Miyuki and Kaguya help Yuu escape the aggro of all his female classmates, let alone win the favor of the girl he`s crushing on? Then, it`s Miyuki who is teaching Chika a new skill for a change. Kaguya faces the temptations and pitfalls of her new smartphone and social media. Ai takes on yet another secret identity. And the student council`s parents cross paths at school conferences where they must decide what colleges their children will apply to.<br><br>When you make plans, the gods laugh.<br><br>Note: The first episode premiered at screenings in Los Angeles and New York on April 2, ahead of the regular TV broadcast on April 9.",
"genres": ["Comedy", "Psychological", "Romance", "School", "Seinen"],
"trailer": "vFN5K-iAyV0"
}
]
## Genres [/anime/genres/{genre}/{type}/{network}/{year}/{sort}{?client_id}]
### Get items filtered by genre, years etc... [GET]
<h4>📄 Pagination 🔓 Token Not Required</h4>
Returns an array of ([Standard Media Object](#introduction/about-simkl-api/standard-media-objects))
This endpoint accepts all parameters from https://simkl.com/anime/all/, select necessary filters and copy parameters
from the url.
Genres API duplicates the urls of the Genres on the website so create a filter on the website and add it to genres API.
+ Parameters
+ genre = all (optional, string, `drama`)
+ type = all-types (optional, string, `series`) ... Type of the series.
+ network = all-networks (optional, string, `tvtokyo`) ... filter by network or production studio
+ year = 2010s (optional, string, `this-week`)
+ sort = rank (optional, string, `popular-this-month`)
+ client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request
Simple query<br>
https://api.simkl.com/anime/genres/drama/2016?client_id=***
Query with all parameters<br>
https://api.simkl.com/anime/genres/all/all-types/all-countries/tvtokyo/all-years/popular-today?client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 200 (application/json)
+ Body
[{
"title": "Kaijuu Girls (Kuro): Ultra Kaijuu Gijinka Keikaku",
"year": 2018,
"date": "2018-11-23T00:00:00+09:00",
"url": "\/anime\/786725\/kaijuu-girls-kuro-ultra-kaijuu-gijinka-keikaku",
"poster": "70\/708168593fa555f00",
"ids": {
"simkl_id": 786725,
"slug": "kaijuu-girls-kuro-ultra-kaijuu-gijinka-keikaku"
},
"rank": null,
"anime_type": "movie",
"ratings": {
"simkl": {
"rating": 10,
"votes": 1
},
"mal": {
"rating": 0,
"votes": 0
}
}
}, {
"title": "Koi to Uso",
"year": 2018,
"date": "2018-11-22T00:00:00+09:00",
"url": "\/anime\/801411\/koi-to-uso",
"poster": "67\/671515560e5acee15",
"ids": {
"simkl_id": 801411,
"slug": "koi-to-uso"
},
"rank": 4126,
"anime_type": "tv",
"ratings": {
"simkl": {
"rating": 5,
"votes": 1
},
"mal": {
"rating": 6.67,
"votes": 65
}
}
}
]
## Premieres [/anime/premieres/{param}{?type}{?client_id}]
### Get latest premieres [GET]
<h4>📄 Pagination 🔓 Token Not Required</h4>
Returns an array of ([Standard Media Object](#introduction/about-simkl-api/standard-media-objects)). Added `anime_type` field, possible values are `tv`,`special`,`ova`,`movie`,`music video`,`ona`.
+ Parameters
+ param (required, string) ...
+ Values
+ `new`
+ `soon`
+ type (optional, string,`all`) ... show only results with this type
+ Values
+ `all`
+ `series`
+ `movies`
+ `ovas`
+ client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request
https://api.simkl.com/anime/premieres/new?client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 200 (application/json)
+ Body
[{
"title": "Kaijuu Girls (Kuro): Ultra Kaijuu Gijinka Keikaku",
"year": 2018,
"date": "2018-11-23T00:00:00+09:00",
"url": "\/anime\/786725\/kaijuu-girls-kuro-ultra-kaijuu-gijinka-keikaku",
"poster": "70\/708168593fa555f00",
"ids": {
"simkl_id": 786725,
"slug": "kaijuu-girls-kuro-ultra-kaijuu-gijinka-keikaku"
},
"rank": null,
"anime_type": "movie",
"ratings": {
"simkl": {
"rating": 10,
"votes": 1
},
"mal": {
"rating": 0,
"votes": 0
}
}
}, {
"title": "Koi to Uso",
"year": 2018,
"date": "2018-11-22T00:00:00+09:00",
"url": "\/anime\/801411\/koi-to-uso",
"poster": "67\/671515560e5acee15",
"ids": {
"simkl_id": 801411,
"slug": "koi-to-uso"
},
"rank": 4126,
"anime_type": "tv",
"ratings": {
"simkl": {
"rating": 5,
"votes": 1
},
"mal": {
"rating": 6.67,
"votes": 65
}
}
}
]
## Airing [/anime/airing?{date}{?sort}{?client_id}]
### Get Airing Anime [GET]
<h4>🔓 Token Not Required</h4>
Returns ongoing Anime ([Standard Media Object](#introduction/about-simkl-api/standard-media-objects))
+ Parameters
+ date (optional, string, `today`) ... only data within this date
+ Values
+ `today`
+ `tomorrow`
+ `22-08-2022`
+ sort (optional, string, `time`) ... sort the results by the specified option
+ Values
+ `time`
+ `rank`
+ `popularity`
+ client_id (required, string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request
https://api.simkl.com/anime/airing?client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 200 (application/json)
+ Body
[
{
"title": "Nights with a Cat",
"year": 2022,
"date": "2022-09-14T12:00:00-05:00",
"poster": "12\/125209937fa1674c4b",
"rank": null,
"url": "\/anime\/1897462\/your-wa-neko-to-issho",
"ids": {
"simkl_id": 1897462,
"slug": "your-wa-neko-to-issho"
},
"episode": {
"episode": 14,
"url": "\/anime\/1897462\/your-wa-neko-to-issho\/episode-14"
},
"anime_type": "tv"
}, {
"title": "Throne of Seal",
"year": 2022,
"date": null,
"poster": "12\/12540566cc860eeeb0",
"rank": 4469,
"url": "\/anime\/1902682\/shen-yin-wangzuo",
"ids": {
"simkl_id": 1902682,
"slug": "shen-yin-wangzuo"
},
"episode": {
"episode": 23,
"url": "\/anime\/1902682\/shen-yin-wangzuo\/episode-23"
},
"anime_type": "ona"
}
]
## Best [/anime/best/{filter}{?type}{?client_id}]
### Get best of all Anime [GET]
<h4>🔓 Token Not Required</h4>
Returns an array of customized ([Standard Media Object](#introduction/about-simkl-api/standard-media-objects))
+ Parameters
+ filter (required, string) ... <b>watched</b> and <b>voted</b> adds additional key in response with the same name
+ Values
+ `year`
+ `month`
+ `all`
+ `voted`
+ `watched`
+ type (optional, string, `all`) ... secondary filter
+ Values
+ `all`
+ `tv`
+ `movies`
+ `ovas`
+ `music`
+ `onas`
+ client_id (required, string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request
https://api.simkl.com/anime/best/watched?client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 200 (application/json)
+ Body
[{
"title": "One Piece",
"year": 1999,
"poster": "72\/7248108487b1ea37",
"url": "\/anime\/38636\/one-piece",
"watched": 765,
"ids": {
"simkl_id": 38636,
"slug": "one-piece"
},
"ratings": {
"simkl": {
"rating": 8.7,
"votes": 774
},
"mal": {
"rating": 8.5,
"votes": 453616
}
}
}, {
"title": "Boruto: Naruto Next Generations",
"year": 2017,
"poster": "68\/6816448e6eb41797e",
"url": "\/anime\/643731\/boruto-naruto-next-generations",
"watched": 577,
"ids": {
"simkl_id": 643731,
"slug": "boruto-naruto-next-generations"
},
"ratings": {
"simkl": {
"rating": 7.7,
"votes": 183
},
"mal": {
"rating": 6.9,
"votes": 94697
}
}
}]
# Group Movies
## Summary [/movies/{id}{?client_id}]
### Get detail info about the movie [GET]
<h4>🔓 Token Not Required ✨ Full Info</h4>
Returns a single detail info about the movie.
+ Parameters
+ id (required, string, `tt1201607`) ... Simkl ID or IMDB ID.
+ client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request
**Short info**, IMDB example:
https://api.simkl.com/movies/tt1201607?client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 200 (application/json)
+ Body
{
"title": "Harry Potter and the Deathly Hallows: Part 2",
"year": 2011,
"type": "movie",
"ids": {
"simkl": 67144,
"slug": "harry-potter-and-the-deathly-hallows-part-2"
}
}
+ Request
**Full info**, IMDB example:
https://api.simkl.com/movies/tt1201607?extended=full&client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 200 (application/json)
+ Body
{
"title": "Harry Potter and the Deathly Hallows: Part 2",
"year": 2011,
"type": "movie",
"ids": {
"simkl": 67144,
"slug": "harry-potter-and-the-deathly-hallows-part-2",
"tmdb": "12445",
"imdb": "tt1201607",
"often": "http:\/\/www.harrypotter.com"
},
"rank": 641,
"poster": "96\/967506e32f7921d4",
"fanart": "96\/967624d7a281067c",
"released": "2011-07-15",
"runtime": 130,
"director": "David Yates",
"certification": "PG",
"budget": 125000000,
"revenue": 1342000000,
"overview": "Harry, Ron and Hermione continue their quest to vanquish the evil Voldemort once and for all. Just as things begin to look hopeless for the young wizards, Harry discovers a trio of magical objects that endow him with powers to rival Voldemort's formidable skills.",
"genres": ["Adventure", "Family", "Fantasy"],
"country": "US",
"ratings": {
"simkl": {
"rating": 8.1,
"votes": 427
},
"imdb": {
"rating": 8.1,
"votes": 607002
}
},
"trailers": [{
"name": "Official Trailer 1",
"youtube": "mObK5XD8udk",
"size": 1080
}, {
"name": "Official Trailer 2",
"youtube": "5NYt1qirBWg",
"size": 1080
}, {
"name": "The Story of Snape",
"youtube": "2nPyasEm3g0",
"size": 720
}],
"release_dates": [{
"iso_3166_1": "BR",
"results": [{
"type": 3,
"release_date": "2011-07-15"
}]
}, {
"iso_3166_1": "CZ",
"results": [{
"type": 3,
"release_date": "2011-07-14"
}]
}, {
"iso_3166_1": "DE",
"results": [{
"type": 5,
"release_date": "2013-08-30"
}]
}, {
"iso_3166_1": "DK",
"results": [{
"type": 3,
"release_date": "2011-07-13"
}]
}, {
"iso_3166_1": "EG",
"results": [{
"type": 3,
"release_date": "2011-07-13"
}]
}, {
"iso_3166_1": "FI",
"results": [{
"type": 3,
"release_date": "2011-07-13"
}]
}, {
"iso_3166_1": "FR",
"results": [{
"type": 3,
"release_date": "2011-07-12"
}]
}, {
"iso_3166_1": "GB",
"results": [{
"type": 3,
"release_date": "2011-07-07"
}]
}, {
"iso_3166_1": "US",
"results": [{
"type": 5,
"release_date": "2011-11-11"
}, {
"type": 3,
"release_date": "2011-07-15"
}]
}]
}
## Trending [/movies/trending/{interval}{?client_id}]
### Get trending movies [GET]
<h4>🔓 Token Not Required ✨ Full Info (Discover)</h4>
You can use any filters from the [Best](https://simkl.com/movies/best-movies/most-watched/) site section.
Select any filter\slider and copy it from the URL to this API endpoint.
This endpoint's default url filters are `?budget=1-500&release=1995-2025&langs=en&wltime=today`
+ Parameters
+ interval = `today` (optional, string, `week`) ... Filter within the time period
+ Values
+ `today`
+ `week`
+ `month`
+ client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request
https://api.simkl.com/movies/trending/?extended=overview,theater,metadata,tmdb,genres&client_id=***
PS: Please use your `client_id`.
+ Body
+ Response 200 (application/json)
+ Body
[
{
"title": "Top Gun: Maverick",
"url": "\/movie\/526230\/top-gun-maverick",
"poster": "12\/12688617391bf69f62",
"fanart": "10\/10868538b672650006",
"ids": {
"simkl_id": 526230,
"slug": "top-gun-maverick",
"tmdb": "361743"
},
"release_date": "05\/04\/2022",
"rank": 170,
"drop_rate": "1.4%",
"watched": 2750,
"plan_to_watch": 1058,
"ratings": {
"simkl": {
"rating": 8.23,
"votes": 582
},
"imdb": {
"rating": 8.4,
"votes": 462046
}
},
"country": "us",
"runtime": "2h 11m",
"status": "ended",
"dvd_date": "08\/25\/2022",
"metadata": "May 4, 2022 \u2022 Budget $170M \u2022 Box office $700,000",
"overview": "After more than thirty years of service as one of the Navy\u2019s top aviators, and dodging the advancement in rank that would ground him, Pete \u201cMaverick\u201d Mitchell finds himself training a detachment of TOP GUN graduates for a specialized mission the likes of which no living pilot has ever seen.",
"trailer":"giXco2jaZ_4",
"genres": ["Action", "Drama"],
"theater": "05\/04\/2022"},
{
"title": "Everything Everywhere All at Once",
"url": "\/movie\/897504\/everything-everywhere-all-at-once",
"poster": "12\/123389099421e4eec0",
"fanart": "12\/125011974ea60ac610",
"ids": {
"simkl_id": 897504,
"slug": "everything-everywhere-all-at-once",
"tmdb": "545611"
},
"release_date": "03\/11\/2022",
"rank": 542,
"drop_rate": "1%",
"watched": 1607,
"plan_to_watch": 684,
"ratings": {
"simkl": {
"rating": 8.21,
"votes": 518
},
"imdb": {
"rating": 8.1,
"votes": 260182
}
},
"country": "us",
"runtime": "2h 20m",
"status": "ended",
"dvd_date": "05\/19\/2022",
"metadata": "March 11, 2022 \u2022 Budget $25M \u2022 Box office $103M",
"overview": "An aging Chinese immigrant is swept up in an insane adventure, where she alone can save what's important to her by connecting with the lives she could have led in other universes.",
"genres": ["Action", "Adventure", "Family", "Science Fiction"],
"theater": "03\/11\/2022"
}
]
## Genres [/movies/genres/{genre}/{type}/{country}/{year}/{sort}{?client_id}]
### Get items filtered by genre, years, etc... [GET]
<h4>📄 Pagination 🔓 Token Not Required</h4>
Returns an array of ([Standard Media Object](#introduction/about-simkl-api/standard-media-objects))
This endpoint accepts all parameters from the [https://simkl.com/movies/all/](https://simkl.com/movies/all/), select the necessary filters and copy parameters from the URL.
Genres API duplicates the URLs of the Genres on the website, so create a filter on the website and add it to the genres API.
+ Parameters
+ genre = all (optional, string, `action`)
+ country = us (optional, string, `gb`) ... Where the movie was released.
+ year = 2010s (optional, string, `this-week`)
+ sort = rank (optional, string, `popular-this-month`)
+ client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request
Simple query
`https://api.simkl.com/movies/genres/action/2016?client_id=***`
Query with all parameters
`https://api.simkl.com/movies/genres/all/all-types/all-countries/all-years/popular-today?client_id=***`
PS: Please use your `client_id`.
+ Response 200 (application/json)
+ Body
```json
[
{
"title": "Toy Story 3",
"year": 2010,
"date": "2010-06-16T00:00:00-05:00",
"url": "/movies/63604/toy-story-3",
"poster": "92/9239026bcfa0c731",
"fanart": "92/9240427e874c8c23",
"ids": {
"simkl_id": 63604,
"slug": "toy-story-3",
"tmdb": 10193
},
"rank": 186,
"ratings": {
"simkl": {
"rating": 7.8,
"votes": 2742
},
"imdb": {
"rating": 8.3,
"votes": 907118
}
}
},
{
"title": "Dangal",
"year": 2016,
"date": "2016-12-21T00:00:00-05:00",
"url": "/movies/524600/dangal",
"poster": "53/5327482ea7bd7c77b",
"fanart": "16/161418093805d34562",
"ids": {
"simkl_id": 524600,
"slug": "dangal",
"tmdb": 360814
},
"rank": 203,
"ratings": {
"simkl": {
"rating": 7.9,
"votes": 377
},
"imdb": {
"rating": 8.3,
"votes": 216570
}
}
},
{
"title": "Dave Chappelle: Sticks & Stones",
"year": 2019,
"date": "2019-08-26T00:00:00-05:00",
"url": "/movies/1153930/dave-chappelle-sticks-and-stones",
"poster": "84/84381468a25ffcf5d",
"fanart": "11/11782778acd57d3e71",
"ids": {
"simkl_id": 1153930,
"slug": "dave-chappelle-sticks-and-stones",
"tmdb": 624932
},
"rank": 244,
"ratings": {
"simkl": {
"rating": 7.7,
"votes": 196
},
"imdb": {
"rating": 8.3,
"votes": 28318
}
}
}
]
```
# Group Sync
Simkl can be one central place where you store all your watch history. Syncing allows all your devices and apps have your watch history up to date. Use Simkl as your a cloud backup for all your Media history.
<h3>Get All Items</h3>
This is a list of all your movies, shows and episodes that you watched or have in your Plan to Watch list.
To start a sync first check the last activities of the user and then do an update only if the date in one of them have changed scince your last check.
## How to Use Sync [/sync/how-to-use-sync]
**How to properly use `date_from` together with the <a href="#reference/sync/last-activities">Last Activities</a> and <a href="#reference/sync/get-all-items">Get All Items</a>
endpoints**
To efficiently synchronize a user's watch history with your application using the Simkl API, you should leverage the `date_from` parameter in conjunction with the <a href="#reference/sync/last-activities">`/sync/activities`</a> endpoint. This allows you to fetch only the data that has changed since your last sync, reducing data transfer and processing time. Below is a step-by-step guide on how to implement this:
### **1. Initial Sync (First Request)**
**a. Call the <a href="#reference/sync/last-activities">Last Activities</a> Endpoint**
Begin by making a request to the <a href="#reference/sync/last-activities">`/sync/activities`</a> endpoint to retrieve the latest activity timestamps for the user. This endpoint provides timestamps for various categories and media types, indicating the last time each was updated.
**Request:**
```http
POST https://api.simkl.com/sync/activities
Headers:
Authorization: Bearer [token]
simkl-api-key: [client_id]
```
**Response Example:**
```json
{
"all": "2023-10-12T09:03:45Z",
"settings": {
"all": "2023-10-10T09:17:15Z"
},
"tv_shows": {
"all": "2023-10-12T09:03:45Z",
"rated_at": "2023-10-11T08:00:00Z",
"plantowatch": "2023-10-12T09:03:45Z",
"watching": "2023-10-10T07:00:00Z",
"completed": "2023-10-09T06:00:00Z",
"hold": null,
"dropped": "2023-10-08T05:00:00Z",
"removed_from_list": "2023-10-07T04:00:00Z"
},
"anime": {
"all": "2023-10-12T09:03:45Z",
"rated_at": "2023-10-10T08:00:00Z",
"plantowatch": "2023-10-11T09:03:45Z",
"watching": "2023-10-09T07:00:00Z",
"completed": "2023-10-08T06:00:00Z",
"hold": null,
"dropped": "2023-10-07T05:00:00Z",
"removed_from_list": "2023-10-06T04:00:00Z"
},
"movies": {
"all": "2023-10-12T09:03:45Z",
"rated_at": "2023-10-11T08:00:00Z",
"plantowatch": "2023-10-10T09:03:45Z",
"completed": "2023-10-09T07:00:00Z",
"dropped": "2023-10-08T06:00:00Z",
"removed_from_list": "2023-10-07T05:00:00Z"
}
}
```
**b. Save the Timestamps**
Store all the datetime values from the response in your application's local or cloud storage. These timestamps will be used to determine changes in the user's data during subsequent syncs.
**c. Fetch All Data Without `date_from`**
Since this is the first sync and you have no prior data, you need to retrieve the entire watchlist.
**Request:**
```http
GET https://api.simkl.com/sync/all-items/
Headers:
Authorization: Bearer [token]
simkl-api-key: [client_id]
```
**Response:**
The API will return all items (movies, shows, anime) that the user has in their watchlist. Process and store this data in your application as the baseline for future syncs.
---
### **2. Subsequent Syncs (Further Requests)**
**a. Periodically Check for Updates**
After some time, check the <a href="#reference/sync/last-activities">`/sync/activities`</a> endpoint for any changes. You can compare the dates from this endpoint with your locally saved copy. You may compare any specific date you need (e.g., `movies.completed`, `tv_shows.watching`) or just the main `all` date (`"all": "2023-10-12T09:03:45Z"`).
To keep your app's data current, periodically check the <a href="#reference/sync/last-activities">`/sync/activities`</a> endpoint for changes. Here are optimal times to perform this check:
- **When the User Opens the App:** Sync immediately to ensure the latest data is displayed.
- **When the App Becomes Active:** If the app was in the background, check for updates when it becomes active again.
- **At Regular Intervals:** For apps that stay open, consider syncing every few hours to keep data fresh.
By syncing during these key moments, your app stays up-to-date without unnecessary API calls.
**Request:**
```http
POST https://api.simkl.com/sync/activities
Headers:
Authorization: Bearer [token]
simkl-api-key: [client_id]
```
**b. Compare Timestamps**
Compare the new timestamps received with the ones you previously saved.
- **If a Timestamp Has Changed:** This indicates that data in that category has been updated since your last sync.
- **If a Timestamp Has Not Changed:** No action is needed for that category.
**Note:** Depending on your application's requirements, you can choose to monitor specific timestamps that are relevant to your data synchronization needs, or you can rely on the main `"all"` timestamp for a broader check.
**c. Use `date_from` Parameter for Updates**
For each category where the timestamp has changed, use the `date_from` parameter in your requests to fetch only the updated data.
**Request Example for Updated Shows:**
```http
GET https://api.simkl.com/sync/all-items/shows/?date_from=2023-10-10T07:00:00Z
Headers:
Authorization: Bearer [token]
simkl-api-key: [client_id]
```
- **`date_from` Value:** Use the saved timestamp from your last sync for that specific category.
**d. Process Updated Data**
Update your local data store with the items received:
- **Add New Items:** Include any new shows, movies, or episodes added.
- **Update Existing Items:** Reflect changes in status, ratings, or watched episodes.
- **Remove Deleted Items:** If the `removed_from_list` timestamp has changed, identify and remove items that are no longer in the user's watchlist.
**Handling Removals:**
If items were removed, you might need to call `/sync/all-items/` without `date_from` only with `extended=simkl_ids_only` or `extended=ids_only` to get the full current list (mini watchlist with IDs only) and compare it with your local data to determine which items have been removed.
**e. Update Saved Timestamps**
After processing the updates, overwrite your saved timestamps with the new ones from the latest <a href="#reference/sync/last-activities">`/sync/activities`</a> response. This ensures your next sync will use the correct `date_from` values.
---
### **3. Detailed Steps with Examples**
#### **First Sync:**
1. **Call <a href="#reference/sync/last-activities">`/sync/activities`</a> and Save Timestamps**
```http
POST https://api.simkl.com/sync/activities
```
Save the entire response.
2. **Fetch All Items Without `date_from`**
```http
GET https://api.simkl.com/sync/all-items/
```
Process and store the data locally.
#### **Subsequent Syncs:**
###### 1. **Call <a href="#reference/sync/last-activities">`/sync/activities`</a>**
```http
POST https://api.simkl.com/sync/activities
```
###### 2. **Compare Timestamps**
Compare each timestamp with the saved ones.
- **Example:** If `movies.rated_at` has changed from `2023-10-11T08:00:00Z` to `2023-10-12T09:00:00Z` (compared to your saved copy), you need to fetch updated movie ratings.
###### 3. **Fetch Updates with `date_from`**
For updated categories, make requests like:
```http
GET https://api.simkl.com/sync/all-items/movies/?date_from=2023-10-11T08:00:00Z
```
###### 4. **Process Updates**
- **Add or Update Items:** Incorporate new data into your local store.
- **Remove Items:** If `removed_from_list` has changed, fetch the full list and remove items not present.
###### 5. **Update Saved Timestamps**
Replace old timestamps with the new ones from the latest <a href="#reference/sync/last-activities">`/sync/activities`</a> response.
---
### **4. Handling Specific Scenarios**
**Ratings Updates:**
- If `rated_at` has changed, use `/sync/ratings` with `date_from` to get the latest ratings.
**Request:**
```http
GET https://api.simkl.com/sync/ratings/?date_from=2023-10-11T08:00:00Z
Headers:
Authorization: Bearer [token]
simkl-api-key: [client_id]
```
**Note on Automatic Moves:**
- When a user rates an item not in their list, it may automatically move to `Completed` or `Watching`. However, the `completed_at` timestamp may not update. Always check ratings when `rated_at` changes.
**Use of Extended Parameters:**
- When needing detailed information (e.g., watched episodes), use `extended=full` and `episode_watched_at=yes`:
```http
GET https://api.simkl.com/sync/all-items/shows/?extended=full&episode_watched_at=yes&date_from=2023-10-10T07:00:00Z
Headers:
Authorization: Bearer [token]
simkl-api-key: [client_id]
```
- **Caution:** These parameters increase response size. Always use them with `date_from` to minimize data transfer.
---
### **5. Tips and Best Practices**
- **Time Zones:** All timestamps are in UTC. Convert them appropriately if your application operates in a different time zone.
- **Error Handling:** Implement robust error handling for network issues or unexpected responses.
- **Data Integrity:** Ensure that your local data store accurately reflects the user's data on Simkl after each sync.
- **Rate Limiting:** Be mindful of API rate limits. Avoid excessive calls by scheduling syncs appropriately.
---
### **6. Summary**
By following these steps, you ensure that:
- Your application stays up-to-date with the user's Simkl watch history.
- Data transfer is minimized by only fetching changes since the last sync.
- The user experiences seamless synchronization without unnecessary delays or data usage.
### Example Workflow Recap [GET]
1. **First Sync:**
- Save all timestamps from <a href="#reference/sync/last-activities">`/sync/activities`</a>.
- Fetch all items without `date_from`.
- Store data locally.
2. **Further Syncs:**
- Call <a href="#reference/sync/last-activities">`/sync/activities`</a> to get new timestamps.
- Compare with saved timestamps.
- For each changed category:
- Use the relevant saved timestamp as `date_from` in `/sync/all-items/` request.
- Process and update local data.
- Update saved timestamps for the next sync.
By properly using `date_from` with the activity endpoint and comparing the specific dates you need or just the main `"all"` date, you optimize your application's performance and provide a better experience for your users.
+ Response 200
## Last Activities [/sync/activities]
### Get last activity [POST]
<h4>🔒 Token Required</h4>
When syncing it's best to check user's last activity first. Then you'll be able to sync only the watchlists that have changed since the last sync.
This method will decrease sync time or minimize wait time to zero if nothing changed so you do not need to download user's full history every time.
<b>NOTE:</b> when user rates the movie, tv show or anime and it is not in his list, it will be automatically moved to `Completed`, `Watching` depending on it's type(movie or series)
<h4>Fields definition and HOWTO</h4>
Name|Description
---|----
`all`| latest update time within the category, use it as first check
`settings`| any update in https://simkl.com/settings/ will trigger update time. For example when user changes his name or time zone.
`rated_at`| if updated check the <i>Get Ratings</i> endpoint with <i>date_from</i> parameter to get latest rating updates/deletes.<br><br> <b>CAUTION!</b> When the user rated a movie it will be automoved to "Completed", but `completed_at` activity field date won't be updated. You should use `/sync/ratings` endpoint with <i>date_from</i> and get those "Completed" items from there(it has all data). <br>Update ratings and statuses(completed,watching) in your app
`plantowatch`<br>`watching`<br>`completed`<br>`hold`<br>`dropped`| Items were added to one of the lists(exc. ratings automove function which won't update this fields) or some episodes were marked/unmarked<br><br>If updated check the <i>Get All Items</i> endpoint with <i>date_from</i> and <i>extended</i> parameters
`removed_from_list`| Check the <i>Get All Items</i> endpoint without <i>date_from</i> and <i>extended</i> parameters to determine which items were removed. <br>If removed items from the lists had ratings, they would be removed
Steps for **how to use it** with `date_from` field:
1. Save all datetime values from this endpoint to your local/cloud storage of the APP
2. Fetch all data from <a href="#reference/sync/get-all-items">*/sync/get-all-items*</a> endpoint without `date_from` field
3. After some time, check this endpoint for any changes(compare the dates from this endpoint with you local saved copy, any specific date you need or just the main `"all": "2016-10-29T09:03:45Z"` date).
4. On dates change
- use the date saved from your 1 step (ex. `"all": "2016-10-29T09:03:45Z"`) as `date_from` field value in <a href="#reference/sync/get-all-items">*/sync/get-all-items*</a> endpoint
- save the new datetime values from this endpoint to your local/cloud storage
- go to step 3
`date_from` field shows all items with the date greater(newer) than date_from field.
If you have any ideas how to make sync even better for you, please [let us know](mailto:support@simkl.com).
+ Request (application/json)
`https://api.simkl.com/sync/activities`
+ Header
Authorization: Bearer [token]
simkl-api-key: [client_id]
+ Response 200 (application/json)
+ Body
{
"all": "2016-10-29T09:03:45Z",
"settings":{
"all":"2015-09-26T09:17:15Z"
},
"tv_shows": {
"all": "2016-10-29T09:03:45Z",
"rated_at": "2016-10-29T09:03:45Z",
"plantowatch": "2016-10-29T09:03:45Z",
"watching": "2016-10-29T09:03:45Z",
"completed": "2016-10-29T09:03:45Z",
"hold": "2016-10-29T09:03:45Z",
"dropped": "2016-10-29T09:03:45Z",
"removed_from_list": "2016-10-29T09:03:45Z"
},
"anime": {
"all": "2016-10-29T09:03:45Z",
"rated_at": "2016-10-29T09:03:45Z",
"plantowatch": "2016-10-29T09:03:45Z",
"watching": "2016-10-29T09:03:45Z",
"completed": "2016-10-29T09:03:45Z",
"hold": null,
"dropped": "2016-10-29T09:03:45Z",
"removed_from_list": "2016-10-29T09:03:45Z",
},
"movies": {
"all": "2016-10-29T09:03:45Z",
"rated_at": "2016-10-29T09:03:45Z",
"plantowatch": "2016-10-29T09:03:45Z",
"completed": "2016-10-29T09:03:45Z",
"dropped": "2016-10-29T09:03:45Z",
"removed_from_list": "2016-10-29T09:03:45Z"
}
}
## Get All Items [/sync/all-items/{type}/{status}{?date_from}]
#### ⚠️ IMPORTANT ⚠️
For continuous sync, DO NOT use without fetching the **Activity** endpoint first.
Always use `date_from` to sync only small changes. This avoids overloading the API server and helps keep it stable for all users.
If you don't follow these rules, your client_id will be suspended.
[How to use Sync](#reference/sync/how-to-use-sync).
### Get all items in the user's watchlist [GET]
<h4>🔒 Token Required ✨ Full Info optional</h4>
Returns all items that user has in his watchlist (watching, plan to watch, dropped, completed), shows, anime, movies.
Anime block has `anime_type` field, possible values are `tv`,`special`,`ova`,`movie`,`music video`,`ona`.
**Note:** If a user doesn't have anything in his watchlists, the response will be `null`
<h4>You can add to the URL:</h4>
Variable|Description
---|----
`extended=full`| adds a list of episodes user have watched
`extended=full_anime_seasons`| same as `full` + TVDB season and episode numbers for every Anime episode. All Anime series including Completed watchlist has American style seasons map added `mapped_tvdb_seasons: [1,2]`.
`extended=simkl_ids_only`| minified response, returns only simkl IDs and slugs.
`extended=ids_only`| minified response, returns only all IDs and slugs without any additionl info.
`episode_watched_at=yes`| adds a time when user watched the episode as `watched_at` time for all episodes
`next_watch_info=yes`| adds more info about next to watch episodes
`memos=yes`| adds member's memo
**IMPORTANT:** Please keep in mind that adding more data to the request (using extended and episode_watched_at) makes the reply exponentially larger, + a few megabytes in most cases, so please use it only when needed and always with the use of `date_from` so that the server reply was very small and fast.
More details on how to use `date_from` field see <a href="#reference/sync/how-to-use-sync">here</a>
+ Request (application/json)
<h6>⚠️ IMPORTANT ⚠️</h6>
<h7>Do not use without fetching the **Activity** endpoint first.</h7>
<h7>Always use `date_from` to sync only small changes. This avoids overloading the API server and helps keep it stable for all users. If you don't follow these rules, your client_id will be suspended.</h7>
<h7>[How to use Sync](#reference/sync/how-to-use-sync).</h7>
<h6>Get list of all the shows, anime and movies in a format of <a href="https://simkl.com/51/tv/">https://simkl.com/51/tv/</a></h6>
`https://api.simkl.com/sync/all-items/`
+ Header
Authorization: Bearer [token]
simkl-api-key: [client_id]
+ Parameters
+ type (optional, string, `anime`) ...
+ Values
+ `shows`
+ `movies`
+ `anime`
+ status (optional, string, `completed`) ...
+ Values
+ `watching`
+ `plantowatch`
+ `hold`
+ `completed`
+ `dropped`
+ date_from (optional, string, `2016-09-12T13:00:30Z`) ... returns the items updated from the passed value
+ Values
+ `2016-09-12T13:00:30Z`
+ extended (optional, string, `full`) ... `full` returns more info including a list of watched episodes
+ Values
+ `full`
+ `full_anime_seasons`
+ `simkl_ids_only`
+ `ids_only`
+ episode_watched_at (optional, string, `yes`) ... `yes` returns the date when user watched the episode
+ Values
+ `yes`
+ memos (optional, string, `yes`) ... `yes` returns memos in addition all other data
+ Values
+ `yes`
+ Response 200 (application/json)
+ Body
{
"shows": [
{
"added_to_watchlist_at":"2010-01-20T20:09:04Z",
"last_watched_at": null,
"user_rated_at": "2021-06-23T13:19:05Z",
"status": "hold",
"user_rating": null,
"last_watched": null,
"next_to_watch": "S01E01",
"watched_episodes_count": 0,
"total_episodes_count": 10,
"not_aired_episodes_count": 0,
"show": {
"title": "Emerald City",
"poster": "51\/5152376528f644b91",
"year": 2017,
"runtime": 40,
"ids": {
"simkl": 583436,
"slug": "emerald-city",
"imdb": "tt3579018",
"zap2it": "EP02431429",
"tmdb": "62417",
"often": "http:\/\/www.nbc.com\/emerald-city",
"tvdb": "295779"
}
}
}
],
"anime": [
{
"added_to_watchlist_at":"2010-01-20T20:09:04Z",
"last_watched_at": "2014-11-06T22:05:52Z",
"user_rated_at": "2021-06-23T13:19:05Z",
"user_rating": 10,
"status": "completed",
"last_watched": "E148",
"next_to_watch": null,
"watched_episodes_count": 150,
"total_episodes_count": 150,
"not_aired_episodes_count": 0,
"anime_type": "tv",
"show": {
"title": "Hunter x Hunter",
"poster": "83\/83975f751784587",
"year": 2011,
"runtime": null,
"ids": {
"simkl": 40398,
"imdb": "tt2098220",
"mal": "11061",
"anidb": "8550"
}
}
},
{
"added_to_watchlist_at":"2010-01-20T20:09:04Z",
"last_watched_at": "2016-10-19T08:34:23Z",
"user_rated_at": "2021-06-23T13:19:05Z",
"user_rating": null,
"status": "plantowatch",
"last_watched": null,
"next_to_watch": "E01",
"anime_type": "tv",
"show": {
"title": "Ajin 2",
"year": 2016,
"runtime": 100,
"ids": {
"simkl": 581835,
"mal": "33253",
"anidb": "12111"
}
}
}
],
"movies": [
{
"added_to_watchlist_at":"2010-01-20T20:09:04Z",
"last_watched_at": "2014-08-09T07:25:55Z",
"user_rated_at": "2021-06-23T13:19:05Z",
"user_rating": null,
"status": "completed",
"movie": {
"title": "Captain America: The First Avenger",
"poster": "84\/842596c6291031c0",
"year": 2011,
"runtime": 120,
"ids": {
"simkl": 55328,
"imdb": "tt0458339",
"tmdb": "1771"
}
}
},
{
"added_to_watchlist_at":"2010-01-20T20:09:04Z",
"last_watched_at": "2014-08-16T18:45:20Z",
"user_rated_at": "2021-06-23T13:19:05Z",
"user_rating": null,
"status": "completed",
"movie": {
"title": "Maleficent",
"poster": "17\/1722048af2197c9a7",
"year": 2014,
"runtime": 100,
"ids": {
"simkl": 195258,
"imdb": "tt1587310",
"tmdb": "102651"
}
}
}
]
}
+ Request (application/json)
<h6>Get Anime list and watched episodes:</h6>
`https://api.simkl.com/sync/all-items/anime/?extended=full`
+ Header
Authorization: Bearer [token]
simkl-api-key: [client_id]
+ Response 200 (application/json)
+ Body
{
"anime": [
{
"added_to_watchlist_at":"2010-01-20T20:09:04Z",
"last_watched_at": "2015-01-06T13:43:26Z",
"user_rated_at": "2021-06-23T13:19:05Z",
"user_rating": 9,
"status": "watching",
"last_watched": "S01E01",
"next_to_watch": "S01E02",
"show": {
"title": "Fate/Stay Night: Unlimited Blade Works",
"year": 2014,
"runtime": 100,
"ids": {
"simkl": 46116,
"imdb": "tt3621796",
"mal": "22297",
"anidb": "9977"
}
},
"seasons": [
{
"number": 1,
"episodes": [
{ "number": 1 },
{ "number": 2 },
{ "number": 3 },
{ "number": 4 },
{ "number": 5 },
{ "number": 6 },
{ "number": 7 },
{ "number": 8 },
{ "number": 9 },
{ "number": 10 },
{ "number": 11 },
{ "number": 12 }
]
}
]
}
]
}
+ Request (application/json)
<h6>Get Anime list and watched episodes:</h6>
`https://api.simkl.com/sync/all-items/anime/?extended=full_anime_seasons`
+ Header
Authorization: Bearer [token]
simkl-api-key: [client_id]
+ Response 200 (application/json)
+ Body
{
"anime": [
{
"added_to_watchlist_at":"2010-01-20T20:09:04Z",
"last_watched_at": "2015-01-06T13:43:26Z",
"user_rated_at": "2021-06-23T13:19:05Z",
"user_rating": 9,
"status": "watching",
"last_watched": "S01E01",
"next_to_watch": "S01E02",
"show": {
"title": "Fate/Stay Night: Unlimited Blade Works",
"year": 2014,
"runtime": 100,
"ids": {
"simkl": 46116,
"imdb": "tt3621796",
"mal": "22297",
"anidb": "9977",
"tvdb": "278626"
}
},
"tvdb_seasons": [2,3],
"seasons": [
{
"number": 1,
"episodes": [
{
"number": 1,
"tvdb": {
"season": 1,
"episode": 1
}
},
{
"number": 2,
"tvdb": {
"season": 1,
"episode": 2
}
},
{
"number": 3,
"tvdb": {
"season": 1,
"episode": 3
}
},
{
"number": 4,
"tvdb": {
"season": 1,
"episode": 4
}
},
{
"number": 5,
"tvdb": {
"season": 1,
"episode": 5
}
},
{
"number": 6,
"tvdb": {
"season": 1,
"episode": 6
}
},
{
"number": 7,
"tvdb": {
"season": 1,
"episode": 7
}
},
{
"number": 8,
"tvdb": {
"season": 1,
"episode": 8
}
},
{
"number": 9,
"tvdb": {
"season": 1,
"episode": 9
}
},
{
"number": 10,
"tvdb": {
"season": 1,
"episode": 10
}
},
{
"number": 11,
"tvdb": {
"season": 1,
"episode": 11
}
},
{
"number": 12,
"tvdb": {
"season": 1,
"episode": 12
}
}
]
}
]
}
]
}
+ Request (application/json)
<h6>Get Anime list with memos:</h6>
`https://api.simkl.com/sync/all-items/anime/?memos=yes`
+ Header
Authorization: Bearer [token]
simkl-api-key: [client_id]
+ Response 200 (application/json)
+ Body
{
"anime": [
{
"added_to_watchlist_at":"2010-01-20T20:09:04Z",
"last_watched_at": "2015-01-06T13:43:26Z",
"user_rated_at": "2021-06-23T13:19:05Z",
"user_rating": 9,
"status": "watching",
"last_watched": "S01E01",
"next_to_watch": "S01E02",
"memo":{
"text": "super memo.",
"is_private": true
},
"show": {
"title": "Fate/Stay Night: Unlimited Blade Works",
"year": 2014,
"runtime": 100,
"ids": {
"simkl": 46116,
"imdb": "tt3621796",
"mal": "22297",
"anidb": "9977"
}
}
}
]
}
## Add Items to the history [/sync/history]
### Add items to watched/watching history [POST]
<h4>🔒 Token Required</h4>
This endpoint lets you add items to a user's watched history.
You can include movies, shows, episodes, or even specific seasons. The more details you provide (like title, year, and IDs), the easier it is for Simkl to match the item correctly.
- **By default, if you don’t specify watchlist status or episodes when adding a show:**
1. **If the show hasn’t been released yet:** It will be added to your *Watching* list.
2. **If the show is still airing:** All aired episodes will be marked as watched.
3. **If the show has ended:** The show will be moved to your *Completed* list.
- **Using `watched_at`:** If you include a UTC datetime in `watched_at`, the item is recorded as watched at that time.
- **Marking as completed:** You can add `status: "completed"` to mark a show as completed. However, if the show is still airing, it will be added to your "watching" watchlist instead and all aired episodes will be marked as watched. The updated watchlist status will be returned in the response.
- **Moving to watching:** You can add `status: "watching"` to keep the show in the Watching watchlist without updating any episodes.
- **List of all supported statuses**: `watching`, `plantowatch`, `completed`, `dropped`, `hold`.
#### Handling Anime Seasons with TVDB/TMDB IDs
By default, anime seasons on Simkl are treated as separate series. To mark all seasons for an anime (when using only TVDB or TMDB IDs) starting from first season, include the flag:
```json
"use_tvdb_anime_seasons": true
```
in the item object.
Each media object should include as much data as possible—especially `title`, `year`, and `ids`—to help Simkl accurately detect the item. You can also include a `watched_at` field to specify the UTC datetime when the item was watched.
if `watched_at` UTC datetime is passed then all will be marked as watched in the past.
Possible values in response for the `anime_type` key see [Standard Media Object](/#introduction/about-simkl-api/standard-media-objects) and for the `simkl_type` are `movie,tv,anime`
<h4>JSON POST DATA</h4>
Key|Type|Value
---|----|-----
`movies`|array| Array of `movie` objects ([see examples](#introduction/about-simkl-api/standard-media-objects))
`shows`|array| Array of `show` objects ([see examples](#introduction/about-simkl-api/standard-media-objects))
`episodes`|array| Array of `episode` objects ([see examples](#introduction/about-simkl-api/standard-media-objects))
<h4>MEDIA OBJECTS POST DATA</h4>
Key|Type|Value
---|----|-----
`item*`|object|movie, show or episode objects
`watched_at`|datetime|UTC datetime when the item was watched
#### Moving between Watchlists
Use ['Add Item to the List'](#reference/sync/add-item-to-the-list/add-items-to-specific-list) if you only need to move items between Watchlists.
+ Request (application/json)
Mark all Titan's seasons as watched. Will put the show into Completed watchlist if the show has ended. If the show is still airing will mark all aired episodes as watched and keep it in Watching watchlist.
+ Header
Authorization: Bearer [token]
simkl-api-key: [client_id]
+ Body
{
"shows": [
{
"added_at": "2010-01-20T20:09:04Z",
"title": "Attack on Titan",
"year": 2013,
"status": "completed",
"use_tvdb_anime_seasons": true,
"ids": {
"simkl": 39687,
"mal": 16498,
"tvdb": 267440,
"imdb": "tt2560140",
"anidb": 9541
}
}
]
}
+ Response 200 (application/json)
+ Body
{
"added": {
"movies": 0,
"shows": 7,
"episodes": 0,
"statuses": [
{
"request": {
"added_at": "2010-01-20T20:09:04Z",
"title": "Attack on Titan",
"year": 2013,
"status": "completed",
"use_tvdb_anime_seasons": true,
"ids": {
"simkl": 39687,
"mal": 16498,
"tvdb": 267440,
"imdb": "tt2560140",
"anidb": 9541
}
},
"response": {
"status": "watching",
"simkl_type": "anime",
"anime_type": "tv"
}
}
]
},
"not_found": {
"movies": [],
"shows": [],
"episodes": []
}
}
+ Request (application/json)
Example request with multiple media types, seasons and episodes
+ Header
Authorization: Bearer [token]
simkl-api-key: [client_id]
+ Body
{
"movies": [
{
"added_at": "2009-01-20T20:09:04Z",
"watched_at": "2011-01-20T20:09:04Z",
"title": "Terminator 3: Rise of the Machines",
"year": "2003",
"rating": 9,
"memo": {
"text": "max 140 chars memo",
"is_private": true
},
"ids": {
"imdb": "tt0181852",
"tmdb": 296,
"simkl": 53536
}
},
{
"ids": {
"simkl": 210728
}
}
],
"shows": [
{
"title": "Attack on Titan",
"year": 2013,
"rating": 0,
"ids": {
"simkl": 39687,
"mal": 16498,
"tvdb": 267440,
"imdb": "tt2560140",
"anidb": 9541
}
},
{
"title": "The Walking Dead",
"year": 2010,
"ids": {
"simkl": 2090,
"tvdb": 153021,
"imdb": "tt1520211"
},
"seasons": [
{
"watched_at": "2011-09-01T14:44:00Z",
"number": 1
},
{
"number": 2,
"episodes": [
{
"number": 1
},
{
"number": 2
}
]
}
]
}
],
"episodes": [
{
"watched_at": "2014-09-01T09:10:11Z",
"ids": {
"simkl": 343633,
"hulu": 681868,
"tvdb": 2493011,
"crunchyroll": 656647
}
}
]
}
+ Request (application/json)
Anime request example
+ Body
{
"shows": [
{
"title": "Attack on Titan",
"year": 2013,
"ids": {
"simkl": 39687,
"mal": 16498,
"tvdb": 267440,
"imdb": "tt2560140",
"anidb": 9541
},
"episodes": [
{
"number": 1
},
{
"number": 2
}
]
}
]
}
+ Response 200 (application/json)
+ Body
+ Request (application/json)
Add the memo to the TV Shows
+ Header
Authorization: Bearer [token]
simkl-api-key: [client_id]
+ Body
{
"shows": [
{
"title": "The Walking Dead",
"year": 2010,
"memo": {
"text": "max 140 chars memo",
"is_private": false
},
"ids": {
"simkl": 2090,
"tvdb": 153021,
"imdb": "tt1520211"
}
}
]
}
+ Response 200 (application/json)
+ Body
{
"added": {
"movies": 0,
"shows": 0,
"episodes": 0,
"statuses": [
{
"request": {
"title": "The Walking Dead",
"year": 2010,
"memo": {
"text": "max 140 chars memo",
"is_private": false
},
"ids": {
"simkl": 2090,
"tvdb": 153021,
"imdb": "tt1520211"
}
},
"response": {
"status": "completed",
"simkl_type": "tv",
"anime_type": null
}
}
]
},
"not_found": {
"movies": [],
"shows": [],
"episodes": []
}
}
## Remove Items from History and from Lists [/sync/history/remove]
### Remove items from watched/watching history [POST]
<h4>🔒 Token Required</h4>
Remove the items from the user's watched history. You can pass shows, seasons, episodes and movies. If no episodes are passed and the season is specified then all episodes within this season will be unmarked. If seasons were skipped too then the show will be removed completely.
When removing show or movie, ratings are removed automatically as well for that item.
<h4>JSON POST DATA</h4>
Key|Type|Value
---|----|-----
`movies`|array| Array of `movie` objects ([see examples](#introduction/about-simkl-api/standard-media-objects))
`shows`|array| Array of `show` objects ([see examples](#introduction/about-simkl-api/standard-media-objects))
<h4>MEDIA OBJECTS POST DATA</h4>
Key|Type|Value
---|----|-----
`item*`|object|movie, show objects
+ Request (application/json)
+ Header
Authorization: Bearer [token]
simkl-api-key: [client_id]
+ Body
{
"movies": [
{
"title": "Terminator 3: Rise of the Machines",
"year": "2003",
"ids": {
"imdb": "tt0181852",
"tmdb": 296,
"simkl": 53536
}
},
{
"ids": {
"simkl": 210728
}
}
],
"shows": [
{
"title": "Attack on Titan",
"year": 2013,
"ids": {
"simkl": 39687,
"mal": 16498,
"tvdb": 267440,
"imdb": "tt2560140",
"anidb": 9541
}
},
{
"title": "The Walking Dead",
"year": 2010,
"ids": {
"simkl": 2090,
"tvdb": 153021,
"imdb": "tt1520211"
},
"seasons": [
{
"number": 2
},
{
"number": 1,
"episodes": [
{
"number": 1
},
{
"number": 2
}
]
}
]
}
]
}
+ Response 200 (application/json)
+ Body
## Get Ratings [/sync/ratings/{type}/{rating}{?date_from}]
### Get all user's ratings [POST]
<h4>🔒 Token Required ✨ Full Info</h4>
Returns all rated items in user's lists filtered by `type`. You can also filter items by rating score. Send a comma separated string if you need a multiple rating items or want to skip items with deleted ratings.
+ Request (application/json)
+ Header
Authorization: Bearer [token]
simkl-api-key: [client_id]
+ Parameters
+ type (optional, string, `anime`) ...
+ Values
+ `shows`
+ `movies`
+ `anime`
+ rating (optional, integer, `8,9,10`) ...
+ Values
+ `1`
+ `2`
+ `3`
+ `4`
+ `5`
+ `6`
+ `7`
+ `8`
+ `9`
+ `10`
+ date_from (optional, string, `2016-09-12T13:00:30Z`) ... returns the items updated from the passed value
+ Values
+ `2016-09-12T13:00:30Z`
+ Response 200 (application/json)
+ Body
{
"shows": [
{
"last_watched_at": "2016-09-12T13:00:30Z",
"user_rated_at": "2021-06-23T13:19:05Z",
"user_rating": 5,
"status": "dropped",
"last_watched": null,
"next_to_watch": "S01E01",
"show": {
"title": "The Last Ship",
"year": 2014,
"ids": {
"simkl": 42040,
"imdb": "tt2402207",
"tvdb": "269533"
}
}
}
],
"anime": [
{
"last_watched_at": "2014-11-06T22:05:52Z",
"user_rated_at": "2021-06-23T13:19:05Z",
"user_rating": 10,
"status": "completed",
"last_watched": "E148",
"next_to_watch": null,
"show": {
"title": "Hunter x Hunter",
"year": 2011,
"ids": {
"simkl": 40398,
"imdb": "tt2098220",
"mal": "11061",
"anidb": "8550"
}
}
}
],
"movies": [
{
"last_watched_at": "2014-08-16T18:45:20Z",
"user_rated_at": "2021-06-23T13:19:05Z",
"user_rating": 6,
"status": "completed",
"movie": {
"title": "Maleficent",
"year": 2014,
"ids": {
"simkl": 195258,
"imdb": "tt1587310",
"tmdb": "102651"
}
}
}
]
}
## Add Ratings [/sync/ratings]
### Add new ratings [POST]
<h4>🔒 Token Required</h4>
Rate the movies or tv shows/anime. You cannot rate the seasons or episodes right now.
If the show/anime or movie is rated before it was in user's list, show will be automatically added to "Watching" list and the movie will be added to "I've seen this" list.
Keep in mind, when removing the show/anime or movie user's ratings will be removed as well for that item.
<h4>JSON POST DATA</h4>
Key|Type|Value
---|----|-----
`movies`|array| Array of `movie` objects ([see examples](#introduction/about-simkl-api/standard-media-objects))
`shows`|array| Array of `show` objects ([see examples](#introduction/about-simkl-api/standard-media-objects)). Anime are `shows` too
+ Parameters
+ rating (required, integer, `10`) ...
+ Values
+ `1`
+ `2`
+ `3`
+ `4`
+ `5`
+ `6`
+ `7`
+ `8`
+ `9`
+ `10`
+ rated_at (optional, string, `2014-09-01T09:10:11Z`) ... UTC datetime
+ Request (application/json)
+ Header
Authorization: Bearer [token]
simkl-api-key: [client_id]
+ Body
{
"movies": [
{
"title": "Terminator 3: Rise of the Machines",
"rating": 8,
"rated_at": "2014-09-01T09:10:11Z",
"year": "2003",
"ids": {
"imdb": "tt0181852",
"tmdb": 296,
"simkl": 53536
}
},
{
"rating": 6,
"ids": {
"simkl": 210728
}
}
],
"shows": [
{
"title": "Attack on Titan",
"year": 2013,
"rating": 10,
"ids": {
"simkl": 39687,
"mal": 16498,
"tvdb": 267440,
"imdb": "tt2560140",
"anidb": 9541
}
}
]
}
+ Response 200 (application/json)
+ Body
{
"added": {
"movies": 2,
"shows": 1,
"statuses": [
{
"request": {
"title": "Terminator 3: Rise of the Machines",
"year": "2003",
"rated_at": "2014-09-01T09:10:11.000Z",
"rating": 8,
"ids": {
"imdb": "tt0181852",
"tmdb": 296,
"simkl": 53536
}
},
"response": {
"status": "completed"
}
},
{
"request": {
"rating": 6,
"ids": {
"simkl": 210728
}
},
"response": {
"status": "completed"
}
},
{
"request": {
"title": "Attack on Titan",
"year": 2013,
"rating": 10,
"ids": {
"simkl": 39687,
"mal": 16498,
"tvdb": 267440,
"imdb": "tt2560140",
"anidb": 9541
}
},
"response": {
"status": "watching"
}
}
]
},
"not_found": {
"movies": [],
"shows": []
}
}
## Remove Ratings [/sync/ratings/remove]
### Remove ratings [POST]
<h4>🔒 Token Required</h4>
Any movies or tv shows passed here will be unrated
<h4>JSON POST DATA</h4>
Key|Type|Value
---|----|-----
`movies`|array| Array of `movie` objects ([see examples](#introduction/about-simkl-api/standard-media-objects))
`shows`|array| Array of `show` objects ([see examples](#introduction/about-simkl-api/standard-media-objects))
<h4>MEDIA OBJECTS POST DATA</h4>
Key|Type|Value
---|----|-----
`item*`|object|movie, show objects
+ Request (application/json)
+ Header
Authorization: Bearer [token]
simkl-api-key: [client_id]
+ Body
{
"movies": [
{
"title": "Terminator 3: Rise of the Machines",
"year": "2003",
"ids": {
"imdb": "tt0181852",
"tmdb": 296,
"simkl": 53536
}
},
{
"ids": {
"simkl": 210728
}
}
],
"shows": [
{
"title": "Attack on Titan",
"year": 2013,
"ids": {
"simkl": 39687,
"mal": 16498,
"tvdb": 267440,
"imdb": "tt2560140",
"anidb": 9541
}
}
]
}
+ Response 200 (application/json)
+ Body
## Add Item to the List [/sync/add-to-list]
### Add items to specific list [POST]
<h4>🔒 Token Required</h4>
Add items to a user's Simkl lists. For example you can add a Show directly to Plan to Watch or move existing show from Watching to Not Interesting. You can pass shows and movies.
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
---|----|-----
`movies`|array| Array of `movie` objects ([see examples](#introduction/about-simkl-api/standard-media-objects))
`shows`|array| Array of `show` objects ([see examples](#introduction/about-simkl-api/standard-media-objects))
<h4>MEDIA OBJECTS POST DATA</h4>
Key|Type|Value
---|----|-----
item*|object|[tv show or movie object](#introduction/about-simkl-api/standard-media-objects).
`to`|string|possible values "plantowatch","completed","watching","hold","dropped"
`to`|array| custom lists **IN DEV**
`watched_at`|datetime|UTC datetime when the item was watched, available only for "completed" status
+ Request (application/json)
+ Header
Authorization: Bearer [token]
simkl-api-key: [client_id]
+ Body
{
"movies": [
{
"title": "Terminator 3: Rise of the Machines",
"to": "completed",
"year": "2003",
"added_at": "2014-09-01T09:10:11Z",
"watched_at": "2014-10-10T22:10:00Z",
"ids": {
"imdb": "tt0181852",
"tmdb": 296,
"simkl": 53536
}
},
{
"to": "plantowatch",
"ids": {
"simkl": 210728
}
}
],
"shows": [
{
"to" : "watching",
"title": "Attack on Titan",
"year": 2013,
"ids": {
"simkl": 39687,
"mal": 16498,
"tvdb": 267440,
"imdb": "tt2560140",
"anidb": 9541
}
},
{
"title": "The Walking Dead",
"year": 2010,
"to": "completed",
"ids": {
"simkl": 2090,
"tvdb": 153021,
"imdb": "tt1520211"
}
}
]
}
+ Response 200 (application/json)
+ Body
{
"added": {
"movies": [
{
"title": "Terminator 3: Rise of the Machines",
"to": "completed",
"year": "2003",
"added_at": "2014-09-01T09:10:11Z",
"watched_at": "2014-10-10T22:10:00Z",
"ids": {
"imdb": "tt0181852",
"tmdb": 296,
"simkl": 53536
}
},
{
"to": "plantowatch",
"ids": {
"simkl": 210728
}
}
],
"shows": [
{
"to" : "watching",
"title": "Attack on Titan",
"year": 2013,
"ids": {
"simkl": 39687,
"mal": 16498,
"tvdb": 267440,
"imdb": "tt2560140",
"anidb": 9541
}
},
{
"title": "The Walking Dead",
"year": 2010,
"to": "watching",
"ids": {
"simkl": 2090,
"tvdb": 153021,
"imdb": "tt1520211"
}
}
]
},
"not_found": {
"movies": [
{
"ids": {
"imdb": "tt0000222"
}
}
],
"shows": []
}
}
## Check if watched [/sync/watched{?extended}]
This endpoint retrieves one or a list of shows, seasons or episodes in a show a user has watched.
### Get specific user's watched items [POST]
<h4>🔒 Token Required</h4>
This endpoint retrieves the list of shows or episodes a user has watched. You can pass different IDs to get their corresponding statuses in the user's watchlist.
The JSON body may contain various IDs (e.g., Simkl, TMDB, IMDB, Netflix, etc.) to check watch status.
#####**Query Parameters**:
- **`extended`** *(optional)* – Controls the level of detail in the response. Possible values:
- `counters` – Includes watched counts only.
- `episodes` – Retrieves all episodes with counters.
- `specials` – Includes special episodes as season `0`, and adjusts counters accordingly.
These values can be combined using a comma (`,`) separator.
**Example:** `?extended=counters,specials`
#####**Limitations**
- When using the `extended` parameter, the request can include a **maximum of 100 items**.
- Exceeding this limit will result in an error.
---
### 📌 JSON Response Data
| Key | Value | Description |
|---------|----------------------------------------|-------------|
| `result` | `true` | The item was found in the user's watchlist. |
| `result` | `false` | The item was found but is not in the user's watchlist. |
| `result` | `not_found` | No match found in the Simkl database using the provided Title, Year, or ID. |
| `list` | `completed`, `watching`, `dropped`, `hold`, `plantowatch` | The user's watchlist category for the item. |
| `last_watched_at` | `YYYY-MM-DDTHH:MM:SSZ` | Last watched date and time of the episode or movie. (UTC format)|
| `episodes_total` | `8` | The total number of episodes in the show or season. |
| `episodes_aired` | `7` | The number of episodes that have aired so far. |
| `episodes_to_be_aired` | `1` | The number of episodes yet to be aired. |
| `episodes_watched` | `6` | The number of episodes the user has watched. |
| `seasons` | `[...]` (array) | A list of seasons for the show. |
| `seasons[].episodes` | `[...]` (array) | A list of episodes in the season. |
+ Parameters
+ extended (optional, string, `counters`) ... You can use multiple values joined by comma.
+ Values
+ `counters`
+ `episodes`
+ `specials`
+ client_id (string) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Attributes (object)
+ Click here to see an **array** of items to check. Each item can include:
+ type (enum[string], optional) - Improves search for TMDb.
+ Members
+ `show`
+ `movie`
+ title: `The Walking Dead` (string, optional) - TV show, anime, or movie title
+ year: 2010 (number, optional) - Release year
+ season: 1 (number, optional) - If set, movies will be ignored (anime typically do not have seasons)
+ episode: 4 (number, optional) - If set, movies will be ignored
+ simkl: 2090 (optional, number, `1`) - Simkl ID
+ hulu: 752375 (number, optional) - Hulu ID (all other parameters can be empty if this is specified)
+ netflix: 70210890 (number, optional) - Netflix movie/show ID (in beta)
+ mal: 4246 (number, optional) - MyAnimeList ID
+ tvdb: 153021 (number, optional) - TVDB ID (all other parameters can be empty if this is specified)
+ tmdb: 76757 (number, optional) - TMDb ID (specify `type` for TV shows; other params can be empty if this is specified)
+ imdb (enum[string], optional) - IMDB ID or full URL (other parameters can be empty if this is specified).
+ Members
+ `tt1520211`
+ `http://www.imdb.com/title/tt1520211/`
+ anidb: 10846 (number, optional) - AniDB ID (all other parameters can be empty if this is specified)
+ crunchyroll: 656641 (number, optional) - Crunchyroll ID (episode ID or URL ID)
+ anilist: 21 (number, optional) - AniList ID
+ kitsu: 12 (number, optional) - Kitsu ID
+ livechart: 321 (number, optional) - LiveChart ID
+ anisearch: 2227 (number, optional) - aniSearch ID
+ animeplanet: `one-piece` (string, optional) - Anime-Planet ID
+ traktslug: `john-wick-chapter-4-2023` (string, optional) - Trakt slug
+ letterboxd: `the-truman-show` (string, optional) - Letterboxd slug
+ Request (application/json)
<h6>Get a list of shows or movies is user has watched them or not</h6>
`https://api.simkl.com/sync/watched/?client_id=***`
+ Header
Authorization: Bearer [token]
simkl-api-key: [client_id]
+ Body
[
{
"netflix": 70262639,
"type": "movie"
},
{
"netflix": 70080650
},
{
"hulu": 764084
}
]
+ Response 200 (application/json)
+ Body
[{
"netflix": 70262639,
"list": "watching",
"result": true,
"last_watched_at": "2017-02-04T16:10:51Z"
},
{
"netflix": 70080650,
"result": false
},
{
"hulu":764084,
"result": "not_found"
}]
+ Request (application/json)
<h6>Get a list of shows with episodes a user has watched including the spesicals season. <br><br>
<i>If you don't need specials, remove it from the extended</i> </h6>
`https://api.simkl.com/sync/watched/?extended=episodes,specials,counters&client_id=***`
+ Header
Authorization: Bearer [token]
simkl-api-key: [client_id]
+ Body
[{
"simkl": 2091057
},{
"imdb": "tt12917170"
}]
+ Response 200 (application/json)
+ Body
[
{
"simkl": 2091057,
"result": true,
"list": "watching",
"last_watched_at": "2025-01-29T15:01:08Z",
"episodes_total": 8,
"episodes_aired": 7,
"episodes_to_be_aired": 1,
"episodes_watched": 6,
"seasons": [
{
"number": 1,
"episodes_total": 8,
"episodes_aired": 7,
"episodes_to_be_aired": 1,
"episodes_watched": 6,
"episodes": [
{
"number": 1,
"watched": true,
"aired": true,
"last_watched_at": "2025-01-29T15:01:03Z"
},
{
"number": 2,
"watched": true,
"aired": true,
"last_watched_at": "2025-01-29T15:01:04Z"
},
{
"number": 3,
"watched": true,
"aired": true,
"last_watched_at": "2025-01-29T15:01:05Z"
},
{
"number": 4,
"watched": true,
"aired": true,
"last_watched_at": "2025-01-29T15:01:06Z"
},
{
"number": 5,
"watched": true,
"aired": true,
"last_watched_at": "2025-01-29T15:01:07Z"
},
{
"number": 6,
"watched": true,
"aired": true,
"last_watched_at": "2025-01-29T15:01:08Z"
},
{
"number": 7,
"watched": false,
"aired": true,
"last_watched_at": null
},
{
"number": 8,
"watched": false,
"aired": false,
"last_watched_at": null
}
]
}
]
},
{
"imdb": "tt12917170",
"result": "not_found"
}
]
# Group Users
User's public data will return all info with GET methods without OAuth\PIN authorization.
## Last Watched Arts [/users/recently-watched-background/{user_id}{?image,client_id}]
Get images for user's last watched TV Show or Movie. Useful for example to create an app that will update user's wallpaper on computer or phone
### Get last watched images and data [GET]
Will reply with user's id, Show\Movie URL, Show\Movie title, large poster, and large fanart image.
*Please cache the image on the device, do not redownload if the same image url.*
+ Parameters
+ user_id = (required, integer, `51`) ... Simkl user id which has public privacy settings.
+ client_id (string) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request https://api.simkl.com/users/recently-watched-background/51?client_id=***
+ Response 200 (application/json)
+ Body
{
"id":342828,
"url":"https://simkl.com/movies/342828/midnight-special",
"title":"Midnight Special",
"poster":"https://simkl.in/posters/30/3082850367420132f_0.jpg",
"fanart":"https://simkl.in/fanart/43/4389778c118f40a6f_0.jpg"
}
### Redirect to last watched image [GET]
Will simply redirect to the image for your app to download or display.
*Please cache the image on the device, do not redownload if the same image url.*
+ Parameters
+ user_id = (required, integer, `51`) ... Simkl user id which has public privacy settings.
+ image = (required, string, `fanart`) ... can be "poster" or "fanart".
+ Values
+ `poster`
+ `fanart`
+ client_id (string) ... Get this from [your app settings](https://simkl.com/settings/developer/).
+ Request https://api.simkl.com/users/recently-watched-background/51?image=fanart&client_id=***
+ Response 302
+ Headers
location: https://simkl.in/fanart/50/500671636445e211e_0.jpg
+ Body
## Settings [/users/settings]
### Receive settings [POST]
<h4>🔒 Token Required</h4>
You can sync user's settings with your apps/site settings
+ Request (application/json)
+ Header
Authorization: Bearer [token]
simkl-api-key: [client_id]
+ Response 200 (application/json)
+ Body
{
"user":
{
"name": "Andrew Masyk",
"joined_at": "2007-11-04T22:04:46Z",
"gender": "male",
"avatar": "https:\/\/graph.facebook.com\/736253775\/picture?width=100&height=100",
"bio": "I'm a founder and developer at simkl.com - a socially powered TV show and movie tracking service",
"loc": "New York, NY, USA",
"age": "30 years"
},
"account":
{
"id" : 51,
"timezone": "America\/New_York",
"type": "free"
},
"connections":
{
"facebook": true
}
}
## Stats [/users/{user_id}/stats]
### Get watched statistics [POST]
<h4>🔒 Token Optional</h4>
Get all info about user's watched movies, tv shows, anime and episodes.
Some users profiles are private so you need to pass token to see their stats
+ Request (application/json)
+ Header
Authorization: Bearer [token]
simkl-api-key: [client_id]
+ Response 201 (application/json)
+ Body
{
"total_mins": 908554,
"movies": {
"total_mins": 171969,
"plantowatch": {
"mins": 18938,
"count": 173
},
"notinteresting": {
"mins": 12969,
"count": 123
},
"completed": {
"mins": 171852,
"count": 1558
}
},
"tv": {
"total_mins": 242560,
"watching": {
"watched_episodes_count": 2612,
"count": 41,
"left_to_watch_episodes": 10276,
"left_to_watch_mins": 411040,
"total_episodes_count": 12888
},
"hold": {
"watched_episodes_count": 1157,
"count": 41,
"left_to_watch_episodes": 828,
"left_to_watch_mins": 33120,
"total_episodes_count": 1985
},
"plantowatch": {
"watched_episodes_count": 243,
"count": 118,
"left_to_watch_episodes": 12961,
"left_to_watch_mins": 518440,
"total_episodes_count": 13204
},
"notinteresting": {
"watched_episodes_count": 184,
"count": 36
},
"completed": {
"watched_episodes_count": 2111,
"count": 55
}
},
"anime": {
"total_mins": 494025,
"watching": {
"watched_episodes_count": 1747,
"count": 21,
"left_to_watch_episodes": 410,
"left_to_watch_mins": 10250,
"total_episodes_count": 2157
},
"hold": {
"watched_episodes_count": 97,
"count": 23,
"left_to_watch_episodes": 462,
"left_to_watch_mins": 11550,
"total_episodes_count": 559
},
"plantowatch": {
"watched_episodes_count": 2324,
"count": 719,
"left_to_watch_episodes": 7829,
"left_to_watch_mins": 195725,
"total_episodes_count": 10153
},
"notinteresting": {
"watched_episodes_count": 662,
"count": 725
},
"completed": {
"watched_episodes_count": 17255,
"count": 1291
}
},
"watched_last_week": {
"total_mins": 130,
"movies_mins": 130,
"tv_mins": 0,
"anime_mins": 0
}
}
# Group Need some help?
<a href="http://uptime.statuscake.com/?TestID=JBfz26Wtd2" title="Website Uptime Monitoring"><img src="https://app.statuscake.com/button/index.php?Track=rVMgFtK0BZ&Days=1&Design=1" /></a>
## CORS
Currently API supports Cross Origin Resource Sharing (CORS) for AJAX requests on the **api.simkl.com** domain. You can read the [CORS W3C working draft](http://www.w3.org/TR/cors), or [this intro](http://code.google.com/p/html5security/wiki/CrossOriginRequestSecurity) from the HTML 5 Security Guide.
## Get in touch
We’re always happy to help you get set up with Simkl. If you're stuck, want to find out more or need to speak to us, [visit our API developer Discord server](https://discord.gg/MJsWNE4) or see the [support center](https://support.simkl.com).