{"id":18300262,"url":"https://github.com/docnow/flatten-tweet","last_synced_at":"2026-02-19T00:34:40.998Z","repository":{"id":57238086,"uuid":"396361905","full_name":"DocNow/flatten-tweet","owner":"DocNow","description":"Make Twitter v2 API response data easier to work with","archived":false,"fork":false,"pushed_at":"2022-07-25T19:24:56.000Z","size":79,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-21T05:32:47.284Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/DocNow.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}},"created_at":"2021-08-15T13:35:23.000Z","updated_at":"2022-07-25T19:24:59.000Z","dependencies_parsed_at":"2022-08-26T14:04:33.321Z","dependency_job_id":null,"html_url":"https://github.com/DocNow/flatten-tweet","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DocNow%2Fflatten-tweet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DocNow%2Fflatten-tweet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DocNow%2Fflatten-tweet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DocNow%2Fflatten-tweet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DocNow","download_url":"https://codeload.github.com/DocNow/flatten-tweet/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247342701,"owners_count":20923642,"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":[],"created_at":"2024-11-05T15:11:54.367Z","updated_at":"2025-10-16T20:26:45.056Z","avatar_url":"https://github.com/DocNow.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# flatten-tweet\n\n## Install\n\n    npm install flatten-tweet\n\n## Use\n\nflatten-tweet is designed to be used to transform the data received from the\nTwitter v2 API to make it easier to work with. It is not a client itself, so\nyou'll need to use something that gives you the raw JSON response (e.g. like\n[twitter-v2]).\n\nThe value in having a separate function to flatten data is that other libraries\nand/or projects can import and use it as needed no matter how the data is being\nfetched. *flatten-tweet* also exports an object `EVERYTHING` which you can use\nto request all expansions and fields, whichever library you might be using.\n\nWhen new expansions or includes are added changed *flatten-tweet* will be\nupdated to include them. [semver] will be used to version the NPM package, with\nrespect to the flatten-tweet JavaScript API (which is pretty simple) but also\nwith respect to the Twitter API. So if a new expansion or field is added you\ncan expect a minor version increment. Any backwards incompatible changes will\nget a new major version.\n\n```javascript\n\nconst Twitter = require('twitter-v2')\nconst { flatten, EVERYTHING }  = require('flatten-tweet')\n\nconst client = new Twitter(credentials)\nconst data = await client.get('tweets/search/recent', {\n  ...EVERYTHING\n  query: 'from:jack'\n})\n\n// flatten it!\n\nconst flattened = flatten(data)\n```\n\n## Huh?\n\nYou might be wondering why you would ever want to use flatten-tweet. Let me\nexplain...\n\nRather than including all the available information for a tweet Twitter's v2\nAPI now includes [expansions] which allow you to request additional information\nlike user, media, quoted/retweeted tweets, etc. This additional information is\nnot included inline in the tweet objects themselves but as an additional JSON\nstanza of `includes`.\n\nThe `includes` stanza cuts down on potential duplication in the response.\nFor example the information about a tweet that is retweeted many times in\nthe tweets contained in the response, is only included once, and\neverywhere else in the response it is referenced using its tweet id.\n\nBut the `includes` stanza also makes processing retrieved Twitter data\na bit more difficult. If you are looking at a tweet and want to know when\nthe tweet author's account was created you can't simply use\n`tweet.author.created_at`. You need to get the `tweet.author_id` and then\nsearch through the `includes.users` list looking for it, and then use\nthat.\n\nTo simplify this process the `flatten()` function included here will take\nan API response, and will copy the includes into all the tweets that\nreference them.\n\nSo now when you are processing a tweet instead of having to work with a tweet\nthat looks (in abbreviated form) like this:\n\n```json\n{\n  \"data\": [\n    {\n      \"id\": \"21\",\n      \"text\": \"just setting up my twttr\",\n      \"author_id\": \"12\"\n    }\n  ],\n  \"includes\": {\n    \"users\": [\n      {\n        \"id\": \"123\",\n        \"username\": \"jack\",\n        \"created_at\": \"2006-03-21T20:50:14.000Z\"\n      }\n    ]\n  }\n}\n```\n\nafter flattening you will have:\n\n```json\n{\n  \"data\": [\n    {\n      \"id\": \"21\",\n      \"text\": \"just setting up my twttr\",\n      \"author_id\": \"12\",\n      \"author\": {\n        \"id\": \"12\",\n        \"username\": \"jack\",\n        \"created_at\": \"2006-03-21T20:50:14.000Z\",\n      }\n    }\n  ]\n}\n```\n\nThis JavaScript is a port of the [equivalent Python function] in [twarc].\n\n## Test\n\nIf you want to run the test suite you'll need to install [twitter-v2] and set\nBEARER_TOKEN in your environment first. Then you can:\n\n    npm run test\n\n[expansions]: https://developer.twitter.com/en/docs/twitter-api/expansions\n[twarc]: https://github.com/docnow/twarc\n[equivalent Python function]: https://github.com/DocNow/twarc/blob/main/twarc/expansions.py\n[semver]: https://semver.org\n[twitter-v2]: https://github.com/HunterLarco/twitter-v2\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocnow%2Fflatten-tweet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdocnow%2Fflatten-tweet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocnow%2Fflatten-tweet/lists"}