{"id":22147451,"url":"https://github.com/megadrive/node-speedrunapi","last_synced_at":"2025-07-26T02:31:49.153Z","repository":{"id":57367286,"uuid":"96894015","full_name":"megadrive/node-speedrunapi","owner":"megadrive","description":"A Promise-based, function-building wrapper for the SpeedRun.com API.","archived":false,"fork":false,"pushed_at":"2022-10-24T04:30:06.000Z","size":91,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-06T18:52:55.168Z","etag":null,"topics":["api","speedrun","speedruncom"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/megadrive.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-07-11T13:07:12.000Z","updated_at":"2019-01-10T15:28:00.000Z","dependencies_parsed_at":"2022-08-23T20:10:19.383Z","dependency_job_id":null,"html_url":"https://github.com/megadrive/node-speedrunapi","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/megadrive%2Fnode-speedrunapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/megadrive%2Fnode-speedrunapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/megadrive%2Fnode-speedrunapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/megadrive%2Fnode-speedrunapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/megadrive","download_url":"https://codeload.github.com/megadrive/node-speedrunapi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227642175,"owners_count":17797850,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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","speedrun","speedruncom"],"created_at":"2024-12-01T23:17:44.664Z","updated_at":"2024-12-01T23:17:45.375Z","avatar_url":"https://github.com/megadrive.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# speedrunapi [![downloads][downloads-image]][downloads-url] [![javascript style guide][standard-image]][standard-url]\n\n[downloads-image]: https://img.shields.io/npm/dm/speedrunapi.svg\n[downloads-url]: https://npmjs.org/package/speedrunapi\n[standard-image]: https://img.shields.io/badge/code_style-standard-brightgreen.svg\n[standard-url]: https://standardjs.com\n[srcom-github]: https://github.com/speedruncom/api\n\n## install\n\n`yarn add speedrunapi` or `npm install --save speedrunapi`\n\n## usage\n\nThis package makes use of `Promises`. No external library is being used, just the native one.\n\n**NOTE: This package does NOT throttle your requests, that is up to you.**\n\nUsing some of the examples from the [Speedrun.com docs][srcom-github] page.\n\n```js\nconst SpeedrunAPI = require('speedrunapi')\nconst sr = new SpeedrunAPI()\n\nsr.games()\n  .exec()\n    .then(response =\u003e {\n      response.items.forEach(function (el) {\n        console.info(el.names.international)\n      })\n    })\n```\n\nThe object will always respond with two elements, `items` and `pagination`. Items can be either an array of items or a single object. Pagination can be `null` depending on the request.\n\n# building requests\n\nThe way this package works is by treating anything after the `{id}` in a docs page as a \"method\" and will have its own function to use. Any method that has a hyphen in it, like `derived-games` reverts to camelCase: `derivedGames`.\n\nUse `param()` to add a parameter to the request. If you'd prefer to add many at once, feel free to use `params()`, which takes an array of objects of key=\u003evalue pairs.\n\nTo make an example, let's recreate this API request and build a request:\n\n```\n/api/v1/games?region=mol4z19n\u0026released=1999\n```\n```js\nsr.games()\n  .param({region: 'mol4z19n'})\n  .param({released: '1999'})\n  .exec()\n    .then(response =\u003e {\n      console.info(response)\n    })\n```\n\nTo get a single `Game`:\n```\n/api/v1/games/v1pxjz68 // retrieves Super Mario Sunshine.\n```\n```js\nsr.games('v1pxjz68')\n  .exec()\n    .then(response =\u003e {\n      console.info(response)\n    })\n```\n\nEmbeds are supported too! Let's get the leaderboards for GTASA 100% and embed the game data too. `yo1yv1q5` is the id for GTASA and `wz27gz20` for the category of 100%.\n\nNote the `[]` around the embed parameter. `embed` expects an array of embeds since it should only be called once.\n\n```\n/api/v1/leaderboards/yo1yv1q5/category/wz27gz20?embed=game\n```\n```js\nsr.leaderboards('yo1yv1q5', 'wz27gz20')\n  .embed(['game'])\n  .exec()\n    .then(response =\u003e {\n      console.info(response)\n    })\n```\n\n## authenticated requests\n\nAllowing authenticated requests is simple.\n\n1. See [Authentication on SpeedrunCom](https://github.com/speedruncom/api/blob/master/authentication.md) on how to get your API key.\n\n2. Copy and paste your API Key a file named `.env` after the `APIKEY=`, so `APIKEY=yourapikey` in a file called `.env`.\n\nNow you can feel free to make authenticated requests. As of writing, the only endpoints that are authenticated are `profile` and `notifications`. If your API key is invalid or unset, your request will throw an error.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmegadrive%2Fnode-speedrunapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmegadrive%2Fnode-speedrunapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmegadrive%2Fnode-speedrunapi/lists"}