🌍 Small World

Where do my Twitter friends live?

Small World downloads everyone you follow on Twitter/X and displays them in a searchable, filterable list and interactive map — all running as a single serverless app on Val Town.

👉 Live demo

The app has three parts:

A lightweight wrapper around the TwitterAPI.io API that handles:

• Fetching all accounts a user follows, with automatic pagination
• Rate-limit retry logic (backs off on 429 responses)
• Memory-efficient streaming via async generators

A script you run to populate your database. It:

• Calls the Twitter API to fetch every account you follow
• Upserts each user into a friends SQLite table with profile info (name, handle, location, bio, avatar, follower count, etc.)
• Handles batching for efficient database writes

An HTTP endpoint that serves a full-featured HTML interface with:

• List view — cards showing each friend's avatar, name, handle, location, and bio, sorted by follower count
• Map view — an interactive Leaflet map with clustered markers using a built-in geocoding dictionary (200+ cities, states, and countries)
• Search — filter by name, handle, location, or bio
• Region filters — quick-filter pills for SF Bay Area, NYC, London, Seattle, Austin, LA, Boston, and more
• Stats — total friends tracked and how many have location data

• A Val Town account
• A TwitterAPI.io API key

1. Fork this val — Click "Fork" on the val page to get your own copy

2. Set your API key — Add an environment variable called twitterapi_key with your TwitterAPI.io key (Val Settings → Environment Variables)

3. Create the database table — Run this SQL in your val's SQLite console or via a script:

   CREATE TABLE IF NOT EXISTS friends (
     id TEXT PRIMARY KEY,
     user_name TEXT NOT NULL,
     name TEXT NOT NULL,
     location TEXT,
     description TEXT,
     url TEXT,
     profile_picture TEXT,
     cover_picture TEXT,
     is_blue_verified INTEGER DEFAULT 0,
     verified_type TEXT,
     followers_count INTEGER DEFAULT 0,
     following_count INTEGER DEFAULT 0,
     statuses_count INTEGER DEFAULT 0,
     favourites_count INTEGER DEFAULT 0,
     media_count INTEGER DEFAULT 0,
     created_at TEXT,
     is_automated INTEGER DEFAULT 0,
     downloaded_at TEXT NOT NULL DEFAULT (datetime('now'))
   );

4. Update the username — In download-friends.ts, change USERNAME to your Twitter handle. In main.ts, update the title/heading to your own name.

5. Download your friends — Run download-friends.ts as a script. This will take a few minutes depending on how many people you follow (the API has rate limits of ~1 request per 5 seconds).

6. Visit your app — Open the HTTP endpoint URL for main.ts to see your friends list and map!

• Add more locations to the GEO_DICT geocoding dictionary in main.ts for better map coverage
• Add region filters for cities where you have lots of friends
• Schedule refresh — convert download-friends.ts to an interval val to auto-refresh weekly
• Use a geocoding API instead of the built-in dictionary for more accurate location mapping

• Runtime: Val Town (Deno-based serverless TypeScript)
• Database: Val Town SQLite (per-project)
• Twitter Data: TwitterAPI.io
• Map: Leaflet + Leaflet.markercluster
• Map Tiles: CARTO (light basemap)