# 부동산 등기 검색



주소 또는 부동산고유번호(14자리)로 열람·발급할 등기 대상을 찾습니다.



인증: Authorization: Bearer $APICK_API_KEY

본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다.

인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다.



## POST /rest/registry_realestate_search 응답 필드

- `data` (object): 요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.

- `data.total` (integer): 'total' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.targets` (array): 'targets' 목록입니다. 각 항목의 구성은 서비스에 따라 다르며, 값이 없으면 빈 배열입니다.

- `data.targets[].index` (integer): 'index' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.targets[].pin` (string): 'pin' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.targets[].kind` (string): 'kind' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.targets[].address` (string): 'address' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.targets[].road_address` (string): 'road_address' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.targets[].lot_address` (string): 'lot_address' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.targets[].status` (string): 현재 처리 상태입니다. 서비스별 상태 값과 다음 행동은 같은 문서의 상태 표를 확인하세요.

- `api` (object): API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.

- `api.success` (boolean): API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.

- `api.cost` (integer): 이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.

- `api.pl_id` (integer): 포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.

## API 요청: POST /rest/registry_realestate_search



### 입력

- `query` (string, 필수): 주소(도로명·지번) 또는 부동산고유번호 14자리 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다.



### 응답 명세

```json

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "total": {
          "type": "integer"
        },
        "targets": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "index": {
                "type": "integer"
              },
              "pin": {
                "type": "string"
              },
              "kind": {
                "type": "string"
              },
              "address": {
                "type": "string"
              },
              "road_address": {
                "type": "string"
              },
              "lot_address": {
                "type": "string"
              },
              "status": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "api": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "cost": {
          "type": "integer"
        },
        "pl_id": {
          "type": "integer"
        }
      }
    }
  }
}

```

### 정적 응답 예시

```json

{
  "data": {
    "total": 1,
    "targets": [
      {
        "index": 1,
        "pin": "111101230010001",
        "kind": "건물",
        "address": "서울특별시 중구 태평로1가 31",
        "road_address": "서울특별시 중구 세종대로 110",
        "lot_address": "서울특별시 중구 태평로1가 31",
        "status": "열람가능"
      }
    ]
  },
  "api": {
    "success": true,
    "cost": 40,
    "pl_id": 12345
  }
}

```

### curl

```curl

curl --fail-with-body --request POST 'https://apick.app/rest/registry_realestate_search' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'query=서울특별시 중구 세종대로 110'

```

### Node.js (서버 ESM)

```javascript

const form = new FormData();
form.append("query", "서울특별시 중구 세종대로 110");
const response = await fetch("https://apick.app/rest/registry_realestate_search", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

```

### python

```python

import os
import requests
parts = [
    ("query", (None, "서울특별시 중구 세종대로 110")),
]
response = requests.request("POST", "https://apick.app/rest/registry_realestate_search",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    files=parts,
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

```

### php

```php

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'query' => '서울특별시 중구 세종대로 110',
];
$curl = curl_init('https://apick.app/rest/registry_realestate_search');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

```

## 코드·오류

## 상세 기능·요금

지원 API 요약 주소나 부동산고유번호로 등기부등본을 열람·발급할 대상을 먼저 찾습니다. 검색 결과의 index를 열람 접수 요청에 그대로 넣습니다. MethodAPI entry point기능성공 결과 POST/rest/registry_realestate_search부동산 등기 대상 검색HTTP 200과 targets

## 상세 요청

요청 파라미터 form-data 전체 예제 보기

## 상세 응답

응답 결과 { "data": { "total": 1, "targets": [ { "index": 1, "pin": "111101230010001", "kind": "건물", "address": "서울특별시 중구 태평로1가 31", "road_address": "서울특별시 중구 세종대로 110", "lot_address": "서울특별시 중구 태평로1가 31", "status": "열람가능" } ] }, "api": { "success": true, "cost": 40, "pl_id": 12345 } } api.cost는 결과가 있을 때만 40P입니다. 결과가 없거나 검색이 실패하면 0P이며 data.targets는 빈 배열입니다.

## 상세 코드·정책

오류와 과금 상황결과 대상 없음HTTP 200, targets: [], 0P 입력 오류HTTP 400 REGISTRY_BAD_REQUEST, 0P 열람·발급 불가 대상HTTP 200, status에 사유 표시 처리 시간 초과·서버 오류오류 응답, 0P