첫 요청 보내기

1. 프로젝트 신청사용 목적과 필요한 분야를 선택하세요. 조회와 자동화 권한은 각각 검토합니다.
2. 승인 후 API 키 발급프로젝트에 승인된 범위에서 키를 만들고 서버 환경 변수에 보관하세요.
3. 서버에서 API 호출응답의 기준일·누락 여부를 확인하고 서비스 출처와 원문 링크를 표시하세요.

curl 'https://playcity.kr/api/developers/v1/block/population?scope=cities&limit=10' \
  -H "Authorization: Bearer $PLAYCITY_API_KEY"

const response = await fetch(
  'https://playcity.kr/api/developers/v1/block/population?scope=cities',
  { headers: { Authorization: `Bearer ${process.env.PLAYCITY_API_KEY}` } }
);
if (!response.ok) throw new Error(`API 요청 실패: ${response.status}`);
const result = await response.json();

import json, os, urllib.request
request = urllib.request.Request(
    'https://playcity.kr/api/developers/v1/block/population?scope=cities',
    headers={'Authorization': 'Bearer ' + os.environ['PLAYCITY_API_KEY']})
with urllib.request.urlopen(request, timeout=30) as response:
    result = json.load(response)

연결할 수 있는 분야

자동화도 기존 권한 안에서

API 승인으로 도시 운영권이나 건물 편집권이 추가되지는 않습니다. 등록과 발행에는 현재 서비스 권한을 확인하고, 같은 요청이 중복 실행되지 않도록 Idempotency-Key를 사용합니다.

분야별 호출량

분·일·월 한도 중 먼저 도달한 한도를 적용합니다. 초기 승인 기준은 아래와 같으며 프로젝트별로 조정할 수 있습니다. 여러 프로젝트의 사용량은 같은 소유자 계정 한도에도 합산됩니다. 한도는 UTC 기준으로 초기화됩니다.

데이터와 원본 서비스

• 응답의 출처와 원문 링크를 이용자에게 표시하세요. 기사·도서·도시 공지 목록은 메타데이터를 제공하며 본문은 원본 서비스에서 확인합니다.
• 인구는 BLOCK의 산정 인구입니다. 등록 세대수를 실제 입주 가구 수로 해석하지 말고, 0과 미등록·미지원 값을 구분하세요.
• 기준일과 갱신 시점을 함께 표시하고 권장 캐시를 활용하세요. 짧은 간격으로 전체 자료를 반복 수집하거나 원본 페이지를 대량 복제하는 용도로 사용하지 마세요.
• 공개 범위의 자료만 제공합니다. 비공개 위치, 원시 활동 로그, 감사 정보, 개인정보, 도서 본문과 내부 관리 API는 제공하지 않습니다.
• API 호출은 광고 노출·페이지 방문·열람·공감으로 집계하지 않습니다. 건물 자동 등록에는 활동 보상을 지급하지 않습니다.

자동 등록과 발행

조회와 쓰기는 별도 승인을 받습니다. 자동 등록·수정은 기존 건물 등록 규칙과 편집 권한을 따르고, 공지·고시는 현재 운영 권한이 있는 도시에서 발행합니다. 플랫폼 전역 공지나 대량 알림 권한은 부여하지 않습니다.

쓰기 요청마다 8~128자의 Idempotency-Key를 보내세요. 같은 프로젝트에서 같은 키와 같은 내용을 다시 보내면 저장된 응답을 반환합니다. 다른 내용은 409로 거부합니다. 결과가 불확정이면 자동 재실행하지 않으며 요청 ID로 결과를 확인해야 합니다. 완료 응답은 90일 동안 보관합니다.

POST /api/developers/v1/block/cities/{citySlug}/notices
Authorization: Bearer <서버 환경 변수의 API 키>
Idempotency-Key: city-notice-20261018-001
Content-Type: application/json

{"title":"도시 운영 안내","body":"공지 내용","purpose":"news"}

오류와 재시도

429 응답은 Retry-After 이후 재시도하세요. 응답의 X-RateLimit-Group과 남은 분·일·월 호출량을 확인할 수 있습니다. 권한·승인 오류는 반복 호출로 해결되지 않습니다. 키는 브라우저·공개 저장소·URL에 넣지 말고, 유출되면 폐기 후 새로 발급하세요.