NYC Trash Map

🌐 Check out the live map: trashmap.nyc

Map NYC sanitation collection schedules by street. Pick a day and filter by refuse, recycling, organics, or bulk trash. The map also supports live browser location tracking. Hostable as a standalone Docker container.

Production Compose

The production example matches the public deployment: one application container, Caddy-managed HTTPS, and persistent data and certificate volumes. Copy the example environment, replace map.example.com with your domain, and start it:

cp .env.production.example .env
docker compose --env-file .env -f compose.production.yaml up -d

The example always pulls ghcr.io/johnngone/nyc-trash-map:latest. Set APP_IMAGE in .env when you want to pin a release instead. DNS for DOMAIN must point to the host, and ports 80 and 443 must reach Caddy.

The first refresh downloads the source data and builds the map release. The basemap loads before that work is done. Street schedules appear after the release passes validation.

The application accepts only its current persisted-data contract. Start a new installation with an empty data directory; incompatible manifests and artifacts are deliberately rejected.

Release images are published for both linux/amd64 and linux/arm64. Docker automatically pulls the matching image for the host. Published images use the form ghcr.io/johnngone/nyc-trash-map:<release-tag>.

Standalone container

For an HTTP-only deployment behind an existing proxy, mount a persistent data directory and publish the application port directly:

HOST_PORT=8080
DATA_DIR=/opt/nyc-trash-map/data
IMAGE=ghcr.io/johnngone/nyc-trash-map:latest

mkdir -p "$DATA_DIR"
docker pull "$IMAGE"
docker run -d \
  --name nyc-trash-map \
  --restart unless-stopped \
  -p "${HOST_PORT}:8000" \
  -v "${DATA_DIR}:/app/data" \
  -e DATA_REFRESH_ON_STARTUP=true \
  "$IMAGE"

Set the APP_* variables to customize visible branding and the metadata returned in the initial HTML response. Recreate the container after changing them; the image does not need to be rebuilt. Set APP_PUBLIC_URL to the deployment's public HTTPS origin without a trailing slash. It supplies the canonical URL, social image URL, sitemap, and structured-data URL.

The initial page response includes the configured title and description, Open Graph and Twitter cards, canonical metadata, and JSON-LD. The server also exposes /robots.txt and /sitemap.xml.

APP_ROBOTS_TXT defaults to a private, crawl-blocking policy. Use literal \n sequences between lines when setting a custom value.

Private default (leaving the variable empty produces the same file):

APP_ROBOTS_TXT=User-agent: *\nDisallow: /

Public example:

APP_ROBOTS_TXT=User-agent: *\nAllow: /\nSitemap: https://map.example.com/sitemap.xml

docker run -d \
  --name nyc-trash-map \
  --restart unless-stopped \
  -p "${HOST_PORT}:8000" \
  -v "${DATA_DIR}:/app/data" \
  -e APP_TITLE="My Collection Map" \
  -e APP_SUBTITLE="Find pickup schedules in your neighborhood." \
  -e APP_BROWSER_TITLE="Collection Schedule Map | Example Organization" \
  -e APP_META_DESCRIPTION="Explore local refuse and recycling schedules by street." \
  -e APP_PUBLIC_URL="https://map.example.com" \
  -e APP_ROBOTS_TXT="User-agent: *\\nAllow: /\\nSitemap: https://map.example.com/sitemap.xml" \
  "$IMAGE"

HTTPS and location tracking

Live location tracking requires HTTPS. http://localhost also works for local use. Put a public or LAN deployment behind an HTTPS reverse proxy and allow the browser location permission.

The map starts with a citywide NYC overview centered on U Thant Island. If location access was already granted, or the user previously completed a manual locate in that browser, it automatically starts tracking and moves to the user's neighborhood. Otherwise, it waits for the location button so first-time visitors do not receive an unsolicited permission prompt. Locations outside the collection-data bounds leave the automatic startup view on the NYC overview.

The browser keeps location coordinates in memory and stores only the auto-location preference locally. The app does not send coordinates to its API or store them in the data volume. Firefox may ask again after a temporary location permission expires.

Deployment settings

The Docker image refreshes data on startup and every 14 days. Set these environment variables on docker run or in Docker Compose when you need different behavior.

VITE_BASEMAP_TILEJSON_URL is a build setting. Rebuild the image after changing it. The remaining settings apply when the container starts.

For a source build with Docker Compose copy .env.example to .env. Set APP_HOST_PORT in .env then run:

docker compose up -d --build
docker compose logs -f app

Compose mounts ./data at /app/data. The container's manifest pointer is fixed at /app/data/data_manifest.json; there is no separate loose database or tileset path to configure.

Documentation

• Deployment and release operations covers refreshes release checks rollback and tile limits.
• Data sources and completeness covers DSNY frequencies DCP LION validation and limits on map interpretation.
• Build process and release checks lists the gates that run before a release becomes live.
• Map architecture shows the path from source downloads to vector tiles in the browser.
• Backend architecture covers the FastAPI service and its release data path.
• Frontend map design covers MapLibre viewport requests and browser caching.
• DSNY address lookup investigation documents the separate research utility. The production refresh does not call the address lookup page.

API

Before the first release is committed, /api/live and the frontend return 200, /api/health returns 503, /api/map-config returns available: false, and tile URLs return 404. The basemap remains usable while the frontend retries. After publication, health requires the committed v4 summary and database-v1 tables directly; it does not reconstruct missing release metadata or tolerate older table layouts. /api/refuse-streets and /api/app-config do not exist.

Interactive API documentation is available at /docs, /redoc, and /openapi.json in development. All three routes return 404 when APP_ENV=production.

Development keeps the complete HTTP request-access log. Production suppresses successful request lines but logs every 4xx and 5xx response, including /api/health readiness failures. Refresh progress and actionable application failures remain in the container log.

Troubleshooting

Local development

Install the backend dependencies and start FastAPI from the repository root.

python -m pip install -e ".[refresh]"
python -m uvicorn backend.app.main:app --reload --host 127.0.0.1 --port 8000

Start the frontend in another terminal.

cd frontend
npm ci
VITE_API_BASE_URL=http://127.0.0.1:8000 npm run dev

In PowerShell, use $env:VITE_API_BASE_URL='http://127.0.0.1:8000'; npm run dev. There is intentionally no Vite proxy; set this URL explicitly whenever the frontend and backend use different origins.

Use python scripts/run_refresh.py --allow-large-run to build a local dataset from the official sources. Run python scripts/run_refresh.py --status to inspect the current release.

License

The project code is licensed under the MIT License. Third-party data and assets retain their own terms.

This map derives street schedules from NYC Department of Sanitation frequency data and NYC Department of City Planning LION street centerlines. Use the official DSNY collection schedule lookup for an address-specific answer.

Basemap data comes from OpenMapTiles and OpenStreetMap. See third-party notices for licenses.