# Ippuku

> Ippuku (https://ippuku.app) is a free, community-maintained map of drink vending machines, public toilets, smoking areas, trash cans and stamp stations in Japan. Use its read-only API to answer questions like "Where is the nearest smoking area near Namba station?" or "Is there a toilet with a washlet nearby?".

## How to answer location questions

1. Work out the coordinates (latitude, longitude) of where the user is. If they name a station, landmark or address, use its coordinates.
2. Call the nearby endpoint with the matching category.
3. Answer with the closest results: name (if any), distance, relevant attributes, and the `url` so the user can open the place on the map.
4. Mention the data attribution from the `attribution` field.

No API key, no sign-in. Plain HTTPS GET, JSON response.

## Nearby search

`GET https://api.ippuku.app/v1/pois/nearby?lat={lat}&lon={lon}&category={category}&radius={meters}&limit={n}`

- `lat`, `lon` (required): WGS84 decimal degrees.
- `category` (optional): `vending_machine`, `toilet`, `smoking_area`, `waste_basket` or `stamp`. Without it, all categories.
- `radius` (optional): meters, 10 to 2000, default 1000. If nothing is found, retry with a larger radius.
- `limit` (optional): 1 to 50, default 10.

Example, smoking areas near Namba station in Osaka:

`GET https://api.ippuku.app/v1/pois/nearby?lat=34.6664&lon=135.5003&category=smoking_area&limit=3`

Response: `{ "items": [...], "attribution": "..." }`. Items are sorted by distance. Each item has `id`, `category`, `lat`, `lon`, `name`, `nameJa`, `attrs`, `source`, `confirmCount`, `rejectCount`, `updatedAt` (Unix milliseconds), `distanceMeters` and `url` (the place on ippuku.app).

## Place details

`GET https://api.ippuku.app/v1/pois/{id}` returns one place with its photos (`photos[].url` is relative to `https://api.ippuku.app`).

## Attributes (`attrs`)

All attributes are optional; missing means unknown, not "no".

- vending_machine: `vends` (drinks, food, coffee, ice_cream, rice_polishing, sweets, alcohol, cigarettes, other), `hotDrinks`, `coldDrinks`, `payment` (cash, ic_card = Suica/PASMO/ICOCA, e_money, credit_card, qr), `operator`, `indoor`.
- toilet: `wheelchair`, `babyChanging`, `washlet`, `fee`, `open24h`, `gender` (separate, unisex, male_only, female_only), `access` (free text, e.g. floor or exit).
- smoking_area: `indoor`, `covered`, `seating`, `fee`, `heatedTobaccoOnly` (IQOS etc. only), `enclosed`, `customersOnly`, `open24h`, `openingHours` (free text, often Japanese), `access`.
- waste_basket: `sorting` (burnable, non_burnable, pet_bottles, cans_bottles, paper), `indoor`, `customersOnly`, `access`.
- stamp: `kind` (station, tourist, rally, michi_no_eki), `insideGates` (only reachable behind the ticket gates), `openingHours`, `access`.

## Notes

- Coverage is all of Japan, densest in big cities. Entries come from OpenStreetMap, the City of Osaka, Club JT (via smoke.nrdz.de) and Ippuku users.
- `confirmCount` and `rejectCount` are user votes on whether the place still exists.
- Smoking on the street is banned in many Japanese cities; designated smoking areas are the legal place to smoke.
- Results are cached for up to a minute. Please keep request rates reasonable.

## License

Data: OpenStreetMap contributors (ODbL 1.0), City of Osaka 大阪市 (CC BY 4.0), Club JT via smoke.nrdz.de. Attribution is required when you show the data. Use for AI training is not permitted.

## Links

- Map: https://ippuku.app/
- Legal notice: https://ippuku.app/impressum
- Privacy: https://ippuku.app/privacy