{"id":34617086,"url":"https://github.com/younes-alhyan/imdb-core","last_synced_at":"2026-01-13T20:09:49.894Z","repository":{"id":329538991,"uuid":"1118528782","full_name":"younes-alhyan/imdb-core","owner":"younes-alhyan","description":"A TypeScript library for interacting with IMDb, allowing full control over user and public lists, searching for titles, and managing watchlists and ratings—directly from code, without relying on the IMDb UI.","archived":false,"fork":false,"pushed_at":"2025-12-26T20:40:54.000Z","size":89,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-28T09:16:43.343Z","etag":null,"topics":["api","automation","entertainment","imdb","imdb-api","imdb-scraper","library","lists","media","movie","npm","ratings","search","tv","typescript","watchlist"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/imdb-core","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/younes-alhyan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-17T22:31:49.000Z","updated_at":"2025-12-26T20:40:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/younes-alhyan/imdb-core","commit_stats":null,"previous_names":["younes-alhyan/imdb-client","younes-alhyan/imdb-core"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/younes-alhyan/imdb-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/younes-alhyan%2Fimdb-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/younes-alhyan%2Fimdb-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/younes-alhyan%2Fimdb-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/younes-alhyan%2Fimdb-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/younes-alhyan","download_url":"https://codeload.github.com/younes-alhyan/imdb-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/younes-alhyan%2Fimdb-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28399849,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","automation","entertainment","imdb","imdb-api","imdb-scraper","library","lists","media","movie","npm","ratings","search","tv","typescript","watchlist"],"created_at":"2025-12-24T14:45:55.526Z","updated_at":"2026-01-13T20:09:49.889Z","avatar_url":"https://github.com/younes-alhyan.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎬 imdb-core\n\n![IMDb](https://img.shields.io/badge/IMDb-F5C518?style=for-the-badge\u0026logo=imdb\u0026logoColor=black)\n![npm](https://img.shields.io/npm/v/imdb-core?style=for-the-badge\u0026color=orange\u0026logo=npm)\n![npm downloads](https://img.shields.io/npm/dt/imdb-core?style=for-the-badge\u0026color=blue\u0026logo=npm)\n![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge\u0026logo=typescript\u0026logoColor=white)\n![Node.js](https://img.shields.io/badge/Node.js-339933?style=for-the-badge\u0026logo=node.js\u0026logoColor=white)\n![License](https://img.shields.io/badge/License-MIT-000000?style=for-the-badge)\n\n## 📦 What is imdb-core?\n\n`imdb-core` is a **TypeScript-friendly library** to interact with IMDb programmatically.  \nIt allows you to access **lists**, **search titles**, manage **watchlists**, and fetch **user activity** directly from your code — the kind of stuff normally only possible via the IMDb UI.\n\n## 🚀 Features\n\n### Lists\n\n- **Predefined Lists**  \n  Access IMDb’s main lists like **ratings**, **watchlist**, **watched history**, and **check-ins**.  \n  Read and manage items in these lists programmatically.\n\n- **User Lists**  \n  Fetch your custom lists, add/remove items, or create new lists with full control.\n\n- **Public Lists**  \n  Access any public IMDb list by its ID. Perfect for reading or processing lists without modifying them.\n\n### Search\n\n- **Title Search**  \n  Search movies, TV shows, podcasts, video games, and more.  \n  Filter and sort results by popularity, ratings, release date, type, and more.\n\n### Titles \u0026 Activity\n\n- **Last Visited**  \n  Fetch recently visited titles from your IMDb account.\n\n- **Ratings**  \n  Add or remove ratings on titles programmatically.\n\n## ⚡ Installation\n\n```bash\nnpm install imdb-core\n```\n\nor\n\n```bash\nyarn add imdb-core\n```\n\n## 💻 Usage Guide\n\n## 1️⃣ Create an IMDb imdbClient\n\n```ts\nimport imdb from \"imdb-core\";\n\nconst imdbClient = imdb.createImdb();\n```\n\nThat’s it. No config yet.\n\n## 2️⃣ Authenticate (set session)\n\nIMDb doesn’t provide a public API, so authentication is done using **cookies**.\n\nYou can either:\n\n- export cookies from your browser\n- or copy the raw cookie string\n\n```ts\nawait imdbClient.setSession({\n  path: \"cookies-imdb-com.txt\",\n});\n```\n\nor\n\n```ts\nawait imdbClient.setSession({\n  cookie: \"YOUR_COOKIE_STRING\",\n});\n```\n\n### Optional: speed it up\n\nIf you already know your IMDb user ID (`urXXXXXXX`), pass it:\n\n```ts\nawait imdbClient.setSession({\n  path: \"cookies-imdb-com.txt\",\n  userId: \"ur1234567\",\n});\n```\n\nThis skips an extra request.\n\n## 3️⃣ Work with your lists\n\n### Predefined lists (built-in IMDb lists)\n\nEvery IMDb account comes with a few built-in lists that track your activity automatically.\n\nWhen you call:\n\n```ts\nconst lists = await imdbClient.getPredefinedLists();\n```\n\nYou get back a record (object) containing up to **four lists**, keyed by their purpose:\n\n```ts\ntype PredefinedListKey = \"ratings\" | \"watchlist\" | \"watchHistory\" | \"checkins\";\n```\n\nEach key maps to the corresponding IMDb list on your account.\n\n#### Options\n\n```ts\nawait imdbClient.getPredefinedLists({\n  isInFavPeopleWeblab,\n  locale,\n});\n```\n\n- `locale` → language / region\n  **Default:** `\"en-US\"`\n\n- `isInFavPeopleWeblab` → internal IMDb experiment flag\n  **Default:** `false`\n  (You can ignore this unless you know you need it.)\n\n### Custom user lists\n\nFetch your own custom lists:\n\n```ts\nconst userLists = await imdbClient.getUserLists();\n```\n\nThis returns an **array of your lists**, created manually from IMDb.\n\n#### Options\n\n```ts\nawait imdbClient.getUserLists({\n  first,\n  locale,\n});\n```\n\n- `first` → number of lists to fetch\n  **Default:** `10`\n\n- `locale` → language / region\n  **Default:** `\"en-US\"`\n\n### Public list\n\nFetch any public IMDb list by its ID:\n\n```ts\nconst publicList = imdbClient.getPublicList(\"ls055592025\");\n```\n\nPublic lists are **read-only**.\n\n### Create a new list\n\n```ts\nconst myList = await imdbClient.createUserList({\n  name: \"Dark \u0026 Psychological\",\n  listDescription: \"Stuff that messes with your head\",\n  visibility: \"PUBLIC\",\n});\n```\n\n#### Options\n\n- `name` → list name (**required**)\n\n- `listDescription` → optional description\n  **Default:** `\"\"`\n\n- `visibility` → `\"PUBLIC\"` or `\"PRIVATE\"`\n  **Default:** `\"PRIVATE\"`\n\n- `listType` → type of list (`\"TITLES\"`, `\"PEOPLE\"`, etc.)\n  **Default:** `\"TITLES\"`\n\n- `allowDuplicates` → allow the same item multiple times\n  **Default:** `true`\n\n### Remove a list\n\n```ts\nawait imdbClient.removeUserList({\n  listId: \"ls055592025\",\n});\n```\n\nThis permanently deletes the list from your account.\n\n## 4️⃣ List objects utilities\n\n### Get list items\n\nFetch all items in a list.\n\n```ts\nconst listItems = await list.getItems();\n```\n\n### Add items to a list\n\nAdds a title to a list.\n\n```ts\nawait list.addItem({ titleId: \"tt0318871\" });\n```\n\n### Options\n\n- `titleId` → IMDb title id (**required**)\n\n- `includeListItemMetadata`\n  **Default:** `false`\n\n- `refTagQueryParam`\n  **Default:** `\"tt_ov_lst\"`\n\n- `originalTitleText`\n  **Default:** `false`\n\n- `isInPace`\n  **Default:** `true`\n\n- `rating` → rating value (1–10)\n  **Required only when adding to the `ratings` list**\n\n### Remove items from a list\n\n```ts\nawait list.removeItem({ titleId: \"tt0318871\" });\n```\n\n## 5️⃣ Search titles\n\nBasic search:\n\n```ts\nconst results = await imdbClient.searchTitle({\n  query: \"berserk\",\n});\n```\n\nWith filters and sorting:\n\n```ts\nconst results = await imdbClient.searchTitle({\n  query: \"god of war\",\n  titleTypes: [\"videoGame\"],\n  sortBy: \"POPULARITY\",\n  sortOrder: \"DESC\",\n});\n```\n\n#### Options\n\n- `query` → search text (**required**)\n\n- `titleTypes` → filter by title type (movies, series, games, etc.)\n  **Default:** all supported title types\n\n- `sortBy` → how results are sorted\n  **Default:** `\"POPULARITY\"`\n\n- `sortOrder` → `\"ASC\"` or `\"DESC\"`\n  **Default:** `\"ASC\"`\n\n- `first` → number of results to return\n  **Default:** `50`\n\n- `locale` → language / region\n  **Default:** `\"en-US\"`\n\n## 6️⃣ Recently visited titles\n\nFetch titles you recently opened on IMDb:\n\n```ts\nconst recent = await imdbClient.getLastVisited({\n  count: 10,\n  locale: \"en-US\",\n});\n```\n\n#### Options\n\n- `count` → number of titles to return\n  **Default:** `10`\n\n- `locale` → language / region\n  **Default:** `\"en-US\"`\n\nUseful for:\n\n- activity tracking\n- history syncing\n- personal dashboards\n\n## 📜 License\n\nThis project is licensed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyounes-alhyan%2Fimdb-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyounes-alhyan%2Fimdb-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyounes-alhyan%2Fimdb-core/lists"}