{"id":24087954,"url":"https://github.com/tinybirdco/santa-tracker-livestream","last_synced_at":"2026-05-15T04:05:21.585Z","repository":{"id":212570668,"uuid":"731766729","full_name":"tinybirdco/santa-tracker-livestream","owner":"tinybirdco","description":"Build a real-time Santa tracker with Tinybird, Confluent, AWS, and Retool","archived":false,"fork":false,"pushed_at":"2023-12-15T14:23:11.000Z","size":25,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-09-17T01:39:29.253Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/tinybirdco.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-14T20:40:19.000Z","updated_at":"2025-01-30T07:46:00.000Z","dependencies_parsed_at":"2023-12-15T02:10:14.931Z","dependency_job_id":"4958600e-1976-4e70-b769-1daabc4a58c4","html_url":"https://github.com/tinybirdco/santa-tracker-livestream","commit_stats":null,"previous_names":["tinybirdco/santa-tracker-livestream"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tinybirdco/santa-tracker-livestream","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinybirdco%2Fsanta-tracker-livestream","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinybirdco%2Fsanta-tracker-livestream/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinybirdco%2Fsanta-tracker-livestream/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinybirdco%2Fsanta-tracker-livestream/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tinybirdco","download_url":"https://codeload.github.com/tinybirdco/santa-tracker-livestream/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinybirdco%2Fsanta-tracker-livestream/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33053154,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-15T02:00:06.351Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2025-01-10T03:56:28.693Z","updated_at":"2026-05-15T04:05:21.569Z","avatar_url":"https://github.com/tinybirdco.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Build a Real-Time Santa Tracker\n\nThis demo builds a real-time application to help Santa deliver toys. This demo consists of:\n* Streaming time-series data from Confluent Cloud that tracks when Santa delivers a toy, and when Santa's inventory gets increased from a workshop. This data stream mimics a Change Data Capture (CDC) that supplis inventory updates coming from a database. \n* An Amazon S3 `children` data store with 50 million toy recipients. \n* A `toys` dimensional table with a list of 106 different toys. \n* A Retool app that is driven by a set of Tinybird API Endpoints.\n\n## Instructions\n\n### 1. Set up a free Tinybird Workspace\n\nNavigate to [tinybird.co/signup](https://www.tinybird.co/signup) and create a free account. Create a new Workspace (name it whatever you want).\n\n### 2. Clone the repository\n\n```bash\ngit clone https://github.com/tinybirdco/santa-tracker.git\ncd santa-tracker\n```\n\n### 3. Install the Tinybird CLI\n\n```bash\npython -mvenv .e\n. .e/bin/activate\npip install tinybird-cli\n```\n\n### 4. Authenticate to Tinybird\n\nCopy your user admin token from [ui.tinybird.co/tokens](https://ui.tinybird.co/tokens). Your user admin token is the token with the format `admin \u003cyour email address\u003e`.\n\nIn the Tinybird CLI, run the following command\n\n```bash\ncd tinybird\nexport TB_TOKEN=\u003cyour user admin token\u003e\ntb auth -i\n```\n\nIf you intend to push this to your own repo, add the `.tinyb` file to your `.gitignore`, as it contains your user admin token.\n\n```bash\necho \".tinyb\" \u003e\u003e .gitignore\n```\n\n### 5. Create the inventory events Data Source in Tinybird\n\nYou're going to capture streaming data from Confluent into Tinybird so you can query it and build your APIs.\n\nYou can do this in the Tinybird UI using the [Confluent Connector](https://www.tinybird.co/docs/ingest/confluent.html), or in the CLI using the following command:\n\n```bash\ntb connection create kafka\n# Kafka Bootstrap Server: \u003cyour Confluent server\u003e\n# Key: \u003cyour Confluent access key\u003e\n# Secret: \u003cyour Confluent secret\u003e\n# Connection name: \u003cGive your connection a name, defaults to bootstrap server\u003e\n```\n\nThen, update the `santa_inventory_cdc.datasource` file as follows:\n\n```\nSCHEMA \u003e\n    `inventory` Int16 `json:$.inventory`,\n    `timestamp` DateTime `json:$.timestamp`,\n    `toy_id` String `json:$.toy_id`\n\nENGINE \"MergeTree\"\nENGINE_PARTITION_KEY \"toYYYYMM(timestamp)\"\nENGINE_SORTING_KEY \"timestamp\"\n\nKAFKA_CONNECTION_NAME \u003cyour connection name\u003e\nKAFKA_TOPIC \u003cyour Confluent topic\u003e\nKAFKA_GROUP_ID \u003cchoose a consumer group ID\u003e\n\n```\n\n### 6. Create the other Data Sources\n\nThis demo is based on two Data Sources, `toys` and `children`. \n\nFor the `toys` Data Source, use the `toy_uuid_generator.py` Python script to generate a list of toys, each with a unique UUID. Once created you can drag and drop it onto the Tinybird UI, or use the \"File Upload\" option to add the Data Source. \n\nFor the `children` Data Source, use the `generate_child_list.py` Python script to create a set of files with children metadata. This script uses the Faker package to generate these child metadata: child_id, child_first_name, child_last_name, latitude, longitude, status, toy_id, naughty_reason. By default, this script will create a single file with 1,000 entries. For the demo, we created 50 files, each with a million entries (!). \n\n### 7. Run the live inventory data generator\n\nThe `santa_inventory_events.py` data generator generates fresh inventory of Santa's toys for delivery. This script creates and writes inventory events to the Kafka stream (with help of the using the `confluent_kafka` Python package). Near the start of the script, be sure to enter your `CONFLUENT_SERVER`, `CONFLUENT_KEY`, and `CONFLUENT_SECRET` details. \n\nThis script has command-line options for both restocking toys (`--restock`) and remove all inventory (`--drop`). There is also a `--speed` option to control the rate at which Santa's inventory gets depleted. \n\nThis script makes calls to the demo `santa_current-inventory` API Endpoint, so it can pick up from where it left off. \n\nWhen restocking, it will loop through the list of toys and created between 50 and 500 of each. \n\n\n### 8. Push the remaining resources to the Tinybird server\n\nPush the remaining Pipes and Data Sources to Tinybird with:\n\n```\ntb push\n```\n\n### 9. Build a frontend!\n\nYou'll now have several Tinybird APIs that you can build with. We used Retool to build a simple frontend application. If you'd like to see how we did that, watch the [recording of our live coding session](https://www.youtube.com/watch?v=RI0k1P6UdLQ)\n\n## Contributing\n\nIf you find any issues or have suggestions for improvements, please submit an issue or a [pull request](https://github.com/tinybirdco/santa-tracker/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc).\n\n## License\n\nThis code is available under the MIT license. See the [LICENSE](https://github.com/tinybirdco/scooter-rental-iot-analytics/blob/main/LICENSE.txt) file for more details.\n\n## Need help?\n\n\u0026bull; [Community Slack](https://www.tinybird.co/community) \u0026bull; [Tinybird Docs](https://www.tinybird.co/docs) \u0026bull;\n\n## Authors\n\n- [Cameron Archer](https://github.com/tb-peregrine)\n- [Jim Moffitt](https://github.com/jimmoffitt)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftinybirdco%2Fsanta-tracker-livestream","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftinybirdco%2Fsanta-tracker-livestream","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftinybirdco%2Fsanta-tracker-livestream/lists"}