{"id":37780247,"url":"https://github.com/emojitracker/emojitrack-streamer-spec","last_synced_at":"2026-01-16T15:05:15.506Z","repository":{"id":16267229,"uuid":"19015402","full_name":"emojitracker/emojitrack-streamer-spec","owner":"emojitracker","description":":dizzy: Emojitracker Steaming API (Specification and Tests)","archived":false,"fork":false,"pushed_at":"2018-07-26T15:13:55.000Z","size":28,"stargazers_count":12,"open_issues_count":0,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-05-21T12:22:56.968Z","etag":null,"topics":["api","documentation","emojitracker","streaming-api","testing-tools"],"latest_commit_sha":null,"homepage":"","language":"CoffeeScript","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/emojitracker.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":"2014-04-22T03:09:47.000Z","updated_at":"2021-05-21T12:44:51.000Z","dependencies_parsed_at":"2022-08-28T03:20:23.143Z","dependency_job_id":null,"html_url":"https://github.com/emojitracker/emojitrack-streamer-spec","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/emojitracker/emojitrack-streamer-spec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emojitracker%2Femojitrack-streamer-spec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emojitracker%2Femojitrack-streamer-spec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emojitracker%2Femojitrack-streamer-spec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emojitracker%2Femojitrack-streamer-spec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emojitracker","download_url":"https://codeload.github.com/emojitracker/emojitrack-streamer-spec/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emojitracker%2Femojitrack-streamer-spec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28479406,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"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","documentation","emojitracker","streaming-api","testing-tools"],"created_at":"2026-01-16T15:05:15.314Z","updated_at":"2026-01-16T15:05:15.487Z","avatar_url":"https://github.com/emojitracker.png","language":"CoffeeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Emojitracker Streaming API :dizzy:\n\nDefines the API spec for the Emojitracker Streaming API, and offer an acceptance\ntest to be run against staging/production servers to verify they meet it.\n\n## Stream API Specifications\n\nAll endpoints are normal HTTP connections, which emit EventSource/SSE formatted\ndata.\n\nCORS headers are set to `*` so anyone can play, please don't abuse the\nprivilege.\n\n### When to use the Streaming API\n\nIn general, use the [REST API][rest-api] to build an initial snapshot state for\na page (or get a one-time use data grab), then use the Streaming API to keep it\nup to date.\n\nDo not repeatedly poll the REST API.  It is intentionally aggressively cached in\nsuch a way to discourage this, in that the scores will only update at a lower\nrate (a few times per minute), meaning you _have_ to use the Streaming API to\nget fast realtime data updates.\n\n(Note that this is a design decision, not a server performance issue.)\n\n[rest-api]: https://github.com/emojitracker/emojitrack-rest-api\n\n### Working with Server Sent Events\n\nSSE is pretty magic. All that talk you've heard of WebSockets? Well they're\ngreat for bidirectional data, but for unidirectional data flow, SSE/EventSource\nis your new best friend.\n\n[\"Stream Updates with Server Sent Events\"][1] by Eric Bidleman from 2010 is\nstill one of the best introductions to SSE in general, and how it compares to\nWebSockets.\n\n\u003e SSEs are sent over traditional HTTP. That means they do not require a special\n\u003e protocol or server implementation to get working. WebSockets on the other\n\u003e hand, require full-duplex connections and new Web Socket servers to handle the\n\u003e protocol. In addition, Server-Sent Events have a variety of features that\n\u003e WebSockets lack by design such as automatic reconnection, event IDs, and the\n\u003e ability to send arbitrary events.\n\n[1]: https://www.html5rocks.com/en/tutorials/eventsource/basics/\n\nThe Emojitracker Streaming API takes advantage of many of these things. Notably,\nunlike the opaque binary format for Websockets, you you can simply curl any\nEmojitracker Streaming API endpoint and read the results with your own eyes.\n\nTry it! It's as simple as `curl https://stream.emojitracker.com/subscribe/eps`.\n\nNow say you want to hook into this with JavaScript? For the most part you\ncan just let the browser's built-in support handle everything for you:\n\n```js\nconst endpoint = \"https://stream.emojitracker.com\";\nlet evsource = new EventSource(`${endpoint}/subscribe/eps`);\nevsource.onmessage = function(event) {\n    console.log(`Received a data update: ${event.data}`);\n}\n```\n\nYou automatically get things like reconnection on disconnect, with zero\nlibraries required.\n\nSome other helpful references on SSE/EventSource:\n\n- [MDN: Using Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)\n- [MDN: EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource)\n\n\n### Streaming API Endpoints\n\nProduction endpoint is: `https://stream.emojitracker.com`. All Streaming API\nendpoints adhere to the _Server Sent Events_ standard. The Emojitracker Streaming\nAPI endpoint is not currently versioned, so there are as of yet no guarantees\nagainst breaking changes (but we try to be reasonable).\n\n#### `/subscribe/eps`\n\nEmits a JSON blob every 17ms (1/60th of a second) containing the unicode IDs\nthat have incremented and the amount they have incremented during that period.\n\nExample:\n\n    data:{'1F4C2':2,'2665':3,'2664':1,'1F65C':1}\n\nIf there have been no updates in that period, in lieu of an empty array, no\nmessage will be sent.  Therefore, do not rely on this for timing data.\n\nSample usage (ES6 Javascript):\n\n```js\nconst endpoint = \"https://stream.emojitracker.com\";\nlet evsource = new EventSource(`${endpoint}/subscribe/eps`);\nevsource.onmessage = function(event) {\n    const updates = JSON.parse(event.data);\n    for (const [k, v] of Object.entries(updates)) {\n        console.log(`Emoji with id ${k} got score increase of ${v}`);\n    }\n}\n```\n\n#### `/subscribe/details/:id`\n\nGet every single tweet as it happens that pertains to the emoji glyph\nrepresented by the unified `id`.\n\nThe tweets are \"ensmallened\" and contain only the absolute minimum amount of\ninformation needed to re-construct the visual display of the tweet without\nadditional API calls to Twitter (for example, the tweet URL is omitted as it can\neasily be reconstructed on the client side using only the screen_name and tweet\nID number).\n\nExample:\n\n    event:stream.tweet_updates.2665\n    data:{\"id\":\"451196288952844288\",\"text\":\"유졍여신에게 화유니가아~♥\\n햇살을 담은 my only one\\n그대인거죠 선물같은 사람 달콤한 꿈속\\n주인공처럼 영원히 with you♥\\nAll about-멜로디데이\\n@GAEBUL_Chicken ♥ @shy1189\\n화윤애끼미랑평생행쇼할텨~?♥\\n#화융자트\",\"screen_name\":\"snowflake_Du\",\"name\":\"잠수탄✻눈꽃두준✻☆글확인\",\"links\":[],\"profile_image_url\":\"http://pbs.twimg.com/profile_images/437227370248806400/aP0fFJOk_normal.jpeg\",\"created_at\":\"2014-04-02T03:15:52+00:00\"}\n\nThe SSE \"event\" field is set with with the namespace, so that you can easily\nbind to it in Javascript with the built-in EventSource.\n\nSample usage (ES6 Javascript):\n\n```js\n// logs all tweets containing 🍑 in realtime\nconst endpoint = \"https://stream.emojitracker.com\";\nlet evsource = new EventSource(`${endpoint}/subscribe/details/1F351`);\nevsource.addEventListener(\"stream.tweet_updates.1F351\", event =\u003e {\n    update = JSON.parse(event.data);\n    console.log(`${update.name} tweeted: ${update.text}`);\n});\n```\n\n## Server/Endpoint Development\n\n### Streaming API Endpoints\n\nThe current production implementation of the Emojitracker Streaming API\nendpoints is handled by [emojitrack-gostreamer]. Go there if you are looking to\nhack on the implementation details.\n\n[emojitrack-gostreamer]: https://github.com/emojitracker/emojitrack-gostreamer\n\n(There were also Ruby and NodeJS implementations, now deprecated.)\n\n### Compliance Testing\n\nThere are some (incomplete) integration tests to verify a Streaing API endpoint\nserver in staging/production, including more detail about HTTP headers, etc.\n\nThis was mainly useful as we experiment with different routing layers and with\nrewriting emojitrack-streamer on different platforms.\n\n    $ STREAM_SERVER=http://host:port npm test\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femojitracker%2Femojitrack-streamer-spec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femojitracker%2Femojitrack-streamer-spec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femojitracker%2Femojitrack-streamer-spec/lists"}