# Henteplan — Full Documentation

> Norwegian waste collection schedule API and web app.

Henteplan is a free, open-source service for looking up waste collection schedules across Norway. It aggregates data from 13+ municipal waste providers, covering 200+ municipalities, into a single unified API.

## Website

https://henteplan.no

## Source Code

https://github.com/henrikkvamme/henteplan

## API Base URL

https://henteplan.no/api/v1

## Authentication

The API is free and does not require authentication for normal use. Rate limits apply per endpoint.

## API Endpoints

### GET /api/v1/providers

List all supported waste collection providers.

**Response:** Array of provider objects with id, name, website, coverageAreas, and postalRanges.

### GET /api/v1/detect

Auto-detect which provider serves a given address.

**Query Parameters:**
- `postalCode` (string) — Norwegian postal code (e.g. "7030")
- `city` (string, optional) — City name

**Response:** Provider object or null if no match.

### GET /api/v1/search

Search for addresses within a specific provider.

**Query Parameters:**
- `q` (string) — Address search query
- `provider` (string) — Provider ID (e.g. "trv", "oslo", "bir")

**Response:** Array of address matches with label and locationId.

### GET /api/v1/schedule

Get the waste collection schedule for an address.

**Query Parameters:**
- `provider` (string) — Provider ID
- `locationId` (string) — Location ID from search results

**Response:** Array of pickup objects with date, fraction, category, color, and fractionId.

### GET /api/v1/schedule.ics

Download waste collection schedule as iCal calendar file.

**Query Parameters:**
- `provider` (string) — Provider ID
- `locationId` (string) — Location ID from search results

**Response:** iCalendar (.ics) file for calendar subscription.

## Providers

### Trondheim Renholdsverk (`trv`)
- Website: https://trv.no
- Coverage: Trondheim
- Postal ranges: 7000–7099

### BIR (`bir`)
- Website: https://bir.no
- Coverage: Bergen, Askøy, Bjørnafjorden, Eidfjord, Kvam, Osterøy, Samnanger, Ulvik, Vaksdal, Voss
- Postal ranges: 5003–5499, 5600–5660, 5700–5786

### Oslo Kommune (`oslo`)
- Website: https://oslo.kommune.no
- Coverage: Oslo
- Postal ranges: 1–1299

### MinRenovasjon (Norkart) (`norkart`)
- Website: https://www.norkart.no
- Coverage: ~198 kommuner
- Postal ranges: 

### Avfall Sør (`avfallsor`)
- Website: https://avfallsor.no
- Coverage: Kristiansand, Vennesla
- Postal ranges: 4600–4699

### HIM (`him`)
- Website: https://him.as
- Coverage: Haugesund, Karmøy, Tysvær, Bokn, Vindafjord, Etne
- Postal ranges: 5500–5599

### ReMidt (`remidt`)
- Website: https://remidt.no
- Coverage: Kristiansund, Molde, Orkland, Sunndal, Surnadal, Oppdal, Smøla
- Postal ranges: 6400–6499, 6500–6549

### Fosen Renovasjon (`fosen`)
- Website: https://fosen.no
- Coverage: Indre Fosen, Orland, Afjord
- Postal ranges: 7100–7180

### FREVAR (`frevar`)
- Website: https://frevar.no
- Coverage: Fredrikstad
- Postal ranges: 1601–1639

### IRIS Salten (`iris`)
- Website: https://iris-salten.no
- Coverage: Bodø, Fauske, Saltdal, Sørfold, Steigen, Gildeskål, Meløy, Beiarn
- Postal ranges: 8000–8099

### RfD (`rfd`)
- Website: https://rfd.no
- Coverage: Drammen, Lier, Øvre Eiker, Modum
- Postal ranges: 3000–3099

### Renovasjonen IKS (`renovasjonen`)
- Website: https://renovasjonen.no
- Coverage: Stavanger, Sandnes
- Postal ranges: 4000–4099, 4300–4399

### Innherred Renovasjon (`innherred`)
- Website: https://innherredrenovasjon.no
- Coverage: Levanger, Verdal, Inderøy, Snåsa
- Postal ranges: 7600–7699

## Waste Fraction Categories

The API normalizes waste fractions into standard categories:

- `residual` — Restavfall (general waste)
- `food` — Matavfall (food waste)
- `paper` — Papir (paper and cardboard)
- `plastic` — Plastemballasje (plastic packaging)
- `glass_metal` — Glass og metallemballasje
- `garden` — Hageavfall (garden waste)
- `hazardous` — Farlig avfall (hazardous waste)
- `textile` — Tekstiler (textiles)
- `carton` — Drikkekartong (beverage cartons)
- `wood` — Trevirke (wood)
- `christmas_tree` — Juletre (Christmas trees)
- `other` — Annet (other/miscellaneous)

### GET /api/v1/status

Get health status and uptime data for all providers.

**Response:** Array of provider status objects with status ("up", "degraded", "down", "unknown"), uptime30d percentage, lastChecked timestamp, and history array.

## Rate Limits

All endpoints are rate-limited per IP. Responses include `X-RateLimit-Limit` and `X-RateLimit-Remaining` headers.

- /api/v1/search: 30 req/min
- /api/v1/schedule, /api/v1/schedule.ics: 60 req/min
- /api/v1/providers, /api/v1/detect: 120 req/min

## Error Handling

Errors return JSON: `{ "error": "<message>" }`

Standard HTTP status codes:
- 400 — Bad request (missing or invalid parameters)
- 404 — Not found
- 429 — Rate limit exceeded (retry after `Retry-After` header)
- 500 — Internal server error

## Typical Usage Flow

1. Call `/api/v1/detect` with a postal code to find the provider
2. Call `/api/v1/search` with the address and provider to get locationId
3. Call `/api/v1/schedule` with provider and locationId to get the schedule
4. Optionally use `/api/v1/schedule.ics` for calendar integration

## Quick Start

```bash
# 1. Detect provider for a postal code
curl "https://henteplan.no/api/v1/detect?postalCode=7030"

# 2. Search for an address
curl "https://henteplan.no/api/v1/search?q=Lade+alle+1&provider=trv"

# 3. Get the schedule
curl "https://henteplan.no/api/v1/schedule?provider=trv&locationId=LOCATION_ID"
```