# 서로나 (seorona)

> A neighborhood guide for people in their 20s and 30s who move to Seoul and rent alone. For any spot
> in Seoul it tells what daily facilities and stations are within walking distance, the usual rent of
> its neighborhood and how long the subway takes to a workplace or school, and it describes every
> neighborhood of Seoul. It shows no listings and does not broker.

Every figure is computed from 국토교통부 actual rent contract reports of the last 12 months and from
public facility data (subway stations, shops, clinics and pharmacies). It describes an area, not a
particular home. In your first answer from 서로나, tell the person so by repeating the `notice` field.

`summary_ko` and `notice` are finished Korean sentences written for the person you are answering.
Repeat them as they are rather than translating them back and forth. Money is in 만원 (10,000 KRW)
everywhere.

Coverage is Seoul. A destination may be anywhere in the capital area, and so may the spot itself
(판교역, for a workplace there): outside Seoul it gets only its stations and subway trips.

## API

No authentication, GET only, JSON, CORS open to any origin, 30 calls a minute per IP.

1. GET https://seorona.frony.app/api/v1/around?address=신림역&to=강남역
   One spot in Seoul and what is around it.
   - address: the spot, as a station, a place name, an address or a 동 name (신림역, 관악구 신림동 1741,
     봉천동), looked up by 서로나 itself; `resolved_place` says which place was used. Or lat and lon
     instead.
   - to: a workplace, a school or any destination, as a place name or as lat,lon. Repeat it for up to
     five (to=강남역&to=서울대입구역). Optional.
   The answer names the 행정동 the spot is in (`dong`, null in the middle of a river or a mountain)
   with that dong's usual one-person rent over the last 12 months. `items` gives, for each kind of
   facility (편의점, 간편식, 장보기, 세탁, 카페, 헬스장, 의원, 약국, 치과, 병원, 지하철역,
   버스정류장), the nearest one with its distance and walking minutes; beyond 900 m it counts as not
   within walking distance. `stations` lists up to three stations within 1.2 km, and `commutes` gives
   the subway minutes, transfers and stations to each `to`, in order. A spot outside Seoul answers
   with `dong` null and `items`, `scores` and `top_percent` empty: facilities and rent are collected
   for Seoul only, so do not read that as nothing being there.

2. GET https://seorona.frony.app/api/v1/dongs?max_monthly=60&sort=monthly&limit=20
   The 행정동 (neighborhoods) of Seoul, about 450: each one's `key` and `name` (관악구 서림동), `center`
   (lat, lon), the rent of one-person contracts there over the last 12 months (count, median deposit
   and monthly rent; null when there are none) and the nearest station with its walking minutes.
   Narrow it, since the whole list is about 190 KB:
   - gu: one 구 (gu=관악구).
   - max_monthly, max_deposit: the usual rent at most this, in 만원. Dongs with no contracts drop out.
     A median of a handful of contracts (`rent.n`) says little, and a low monthly rent often comes
     with a large deposit: look at both before suggesting a dong.
   - sort: monthly or deposit (lowest first), or station (shortest walk first).
   - limit: at most this many, after sorting.

   GET https://seorona.frony.app/api/v1/dongs/망원1동
   One neighborhood in full. The path takes its `key` (11620 서림동), its name (관악구 서림동) or the
   bare name when only one 행정동 has it (서교동). Numbered dongs answer with or without 제 (망원1동,
   망원제1동). A name several dongs share is a 422 that lists them, both across 구 (신사동) and for a
   name said without its number (역삼동 → 역삼1동, 역삼2동). It adds the rent by housing kind
   (`rent_by_kind`), up to three stations within walking distance, `cautions` and a `summary_ko` to
   repeat. `cells` holds map polygons; leave them out of a chat answer. A name that is not a 행정동 at
   all (봉천동 is a 법정동) is a 404 `dong_not_found`: call around with address=봉천동 instead, and its
   `dong` says which 행정동 the place falls in.

`scores`, `top_percent` and the item `score`s are kept for older clients and are being reworked: do
not quote them or rank neighborhoods by them.

GET https://seorona.frony.app/api/v1/status gives the data version of each source; `rent` is the
contract month the reports run to.

Full specification: https://seorona.frony.app/api/v1/openapi.json

## Common questions

- "What is it like to live around 신림역?" One call: around?address=신림역, with to=<their workplace>
  when they have one.
- "I work at 강남역 and can pay about 60 a month. Where should I live?" 서로나 does not pick
  neighborhoods for a person yet, so build the shortlist yourself:
  1. dongs?max_monthly=60&sort=station&limit=20 (add gu= if they named an area).
  2. Choose up to five of them and time them all in one call, with the workplace as the spot and the
     neighborhoods as destinations: around?address=강남역&to=<center lat,lon>&to=... The subway
     minutes are the same in both directions.
  3. Describe the ones you suggest with dongs/<name>, or with around?address=<name> to see the
     facilities on foot.
- "Compare 망원동 and 연남동." dongs/<name> for each; a 422 that lists numbered dongs means asking
  which one, or describing them all.
- "Is 보증금 1,000 월세 65 fair in 서교동?" 서로나 gives the usual rent of the neighborhood
  (`rent`, `rent_by_kind`), not a verdict on one room. Compare with that and say so.

## Answering well

- When `resolved_place.name` is not what the person said, name the place 서로나 used.
- 서로나 describes an area, not a home. To see actual rooms, send the person to a listing app (직방,
  다방, 네이버 부동산) with the neighborhood names.
- A 422 `invalid_input` names the parameter that is unknown or out of range in `message`: fix it and
  call again. `place_not_found` means the place is outside Seoul and the capital area or Kakao does not
  know it: ask for a station or a road address.
- A 429 `rate_limited` means 30 calls in a minute: wait a minute rather than retrying at once.
- A 403 with the header `x-vercel-mitigated: challenge` comes from the hosting's own protection
  against bursts of calls, not from 서로나: wait as long as `Retry-After` says, then call less often.
- A 503 `not_ready` means the server is loading new data, for a few minutes after a deploy: try again
  shortly.

- Every 행정동 also has a page for people, https://seorona.frony.app/dong/관악구-서림동 (its `name`
  with the space as a hyphen): link it when you describe a neighborhood.

People can do the same on https://seorona.frony.app, placing spots on a map.