# 토지 종합 분석



필지의 지목·면적·용도지역·공시지가 이력·토지이동이력을 모아 공시지가 변동률·연평균 변동률·추세·규제 저촉을 분석합니다.



인증: Authorization: Bearer $APICK_API_KEY

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

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



## POST /rest/land_info 응답 필드

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

- `data.PNU` (string): 확정된 필지고유번호 19자리입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.소재지` (string): 주소로 조회했을 때 확정된 주소입니다. pnu로 조회하면 빈 문자열입니다.

- `data.지번` (string): 주소로 조회했을 때의 지번 표기입니다. pnu로 조회하면 빈 문자열입니다.

- `data.법정동코드` (string): 법정동코드 10자리입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.지역코드` (string): 시군구 단위 지역코드 5자리입니다. 실거래가 조회 등에 그대로 씁니다. pnu로 조회하면 빈 문자열일 수 있습니다.

- `data.좌표` (object): 경위도 좌표(x 경도, y 위도)입니다. pnu로 조회하면 null입니다. null 허용.

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

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

- `data.기준연도` (string): 실제로 적용된 기준연도입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.필지` (object): 필지 기본정보입니다. 가져오지 못하면 null입니다. 하위 필드에 코드·이름·상태 같은 세부 값이 들어 있으며, 자료가 없으면 빈 객체이거나 생략됩니다. null 허용.

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

- `data.필지.법정동코드` (string): '법정동코드' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.필지.법정동` (string): 주소를 구성하는 행정구역·지번 정보입니다. 같은 거래라도 표기 기준에 따라 값이 달라질 수 있으므로 도로명 주소와 함께 확인하세요.

- `data.필지.지번` (string): 본번-부번 표기입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.필지.지목` (string): 지목 이름입니다. 예: 대, 전, 임야 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.필지.면적` (number): 토지 면적(㎡)입니다. 값이 없으면 null입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. null 허용.

- `data.필지.필지구분` (string): 대장 구분 표기입니다. 예: 토지대장, 임야대장 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.토지특성` (object): 기준연도의 토지특성입니다. 가져오지 못하거나 그해 자료가 없으면 null입니다. null 허용.

- `data.토지특성.지목` (string): '지목' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

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

- `data.토지특성.용도지역_1` (string): 첫 번째 용도지역입니다. 예: 제2종일반주거지역 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.토지특성.용도지역_2` (string): 두 번째 용도지역입니다. 없으면 빈 문자열입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.토지특성.토지이용상황` (string): 실제 이용 상황입니다. 예: 상업용, 단독 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.토지특성.지형고저` (string): 지형의 높낮이입니다. 예: 평지 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.토지특성.지형형상` (string): 필지 모양입니다. 예: 가로장방 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.토지특성.도로접면` (string): 도로에 닿은 형태입니다. 예: 광대로한면 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.토지특성.기준일자` (string): '기준일자' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.공시지가` (array): 연도별 개별공시지가입니다. 최근 연도부터 정렬하며, 자료가 없는 연도는 빠집니다.

- `data.공시지가[].기준연도` (string): 공시 기준연도입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.공시지가[].기준일자` (string): '기준일자' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.공시지가[].단위면적당가격` (integer): ㎡당 개별공시지가(원)입니다. 토지 전체 가격은 필지.면적을 곱해 구합니다.

- `data.토지이용계획` (array): 필지에 걸린 용도지역·지구·구역 목록입니다. 없으면 빈 배열입니다. 각 항목의 구성은 서비스에 따라 다르며, 값이 없으면 빈 배열입니다. 항목 수와 순서를 함께 확인하세요.

- `data.토지이용계획[].용도지역지구구역` (string): 지역·지구·구역 이름입니다. 예: 도시지역, 가축사육제한구역 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.토지이용계획[].저촉여부` (string): 필지가 그 구역에 포함·저촉되는지 표기입니다. 예: 포함, 저촉, 접합 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.토지이용계획[].근거법령` (string): '근거법령' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.토지이용계획[].기준일자` (string): '기준일자' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.토지이동이력` (array): 분할·합병·지목변경 같은 토지 이동 이력입니다. 없으면 빈 배열입니다. 각 항목의 구성은 서비스에 따라 다르며, 값이 없으면 빈 배열입니다. 항목 수와 순서를 함께 확인하세요.

- `data.토지이동이력[].이동일자` (string): 이동이 일어난 날짜입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.토지이동이력[].이동사유` (string): 이동 사유입니다. 예: 분할, 지목변경 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.토지이동이력[].기준일자` (string): '기준일자' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

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

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

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

- `api.ms` (integer): 서버가 요청을 받아 응답 본문을 만들기까지 걸린 처리 시간(밀리초)입니다. 네트워크 왕복 시간과 클라이언트 대기 시간은 포함되지 않습니다.

## API 요청: POST /rest/land_info



### 입력

- `pnu` (string, 조건부): 필지고유번호 (19자리) 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다.

- `address` (string, 조건부): 지번 또는 도로명 주소 (pnu 가 없을 때 사용) 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다.

- `addrType` (string, 선택): 주소 유형 (기본 auto) 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. 가능한 값은 3가지입니다. parcel = 지번 주소를 기준으로 조회하는 값입니다. road = 도로명 주소를 기준으로 조회하는 값입니다. auto = 서버·모델이 상황에 맞춰 자동으로 정하는 값입니다. 별도 지정이 필요 없습니다. 허용값: parcel, road, auto

- `year` (string, 선택): 토지특성·공시지가 기준연도 (기본 전년도) 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다.

- `priceYears` (integer, 선택): 공시지가 이력 연수 (1~5, 기본 3) 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.



### 응답 명세

```json

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "PNU": {
          "type": "string",
          "description": "확정된 필지고유번호 19자리입니다."
        },
        "소재지": {
          "type": "string",
          "description": "주소로 조회했을 때 확정된 주소입니다. pnu로 조회하면 빈 문자열입니다."
        },
        "지번": {
          "type": "string",
          "description": "주소로 조회했을 때의 지번 표기입니다. pnu로 조회하면 빈 문자열입니다."
        },
        "법정동코드": {
          "type": "string",
          "description": "법정동코드 10자리입니다."
        },
        "지역코드": {
          "type": "string",
          "description": "시군구 단위 지역코드 5자리입니다. 실거래가 조회 등에 그대로 씁니다. pnu로 조회하면 빈 문자열일 수 있습니다."
        },
        "좌표": {
          "type": "object",
          "properties": {
            "x": {
              "type": "number"
            },
            "y": {
              "type": "number"
            }
          },
          "description": "경위도 좌표(x 경도, y 위도)입니다. pnu로 조회하면 null입니다.",
          "nullable": true
        },
        "기준연도": {
          "type": "string",
          "description": "실제로 적용된 기준연도입니다."
        },
        "필지": {
          "type": "object",
          "properties": {
            "PNU": {
              "type": "string"
            },
            "법정동코드": {
              "type": "string"
            },
            "법정동": {
              "type": "string",
              "description": "법정동 이름입니다."
            },
            "지번": {
              "type": "string",
              "description": "본번-부번 표기입니다."
            },
            "지목": {
              "type": "string",
              "description": "지목 이름입니다. 예: 대, 전, 임야"
            },
            "면적": {
              "type": "number",
              "description": "토지 면적(㎡)입니다. 값이 없으면 null입니다.",
              "nullable": true
            },
            "필지구분": {
              "type": "string",
              "description": "대장 구분 표기입니다. 예: 토지대장, 임야대장"
            }
          },
          "description": "필지 기본정보입니다. 가져오지 못하면 null입니다.",
          "nullable": true
        },
        "토지특성": {
          "type": "object",
          "properties": {
            "지목": {
              "type": "string"
            },
            "면적": {
              "type": "number"
            },
            "용도지역_1": {
              "type": "string",
              "description": "첫 번째 용도지역입니다. 예: 제2종일반주거지역"
            },
            "용도지역_2": {
              "type": "string",
              "description": "두 번째 용도지역입니다. 없으면 빈 문자열입니다."
            },
            "토지이용상황": {
              "type": "string",
              "description": "실제 이용 상황입니다. 예: 상업용, 단독"
            },
            "지형고저": {
              "type": "string",
              "description": "지형의 높낮이입니다. 예: 평지"
            },
            "지형형상": {
              "type": "string",
              "description": "필지 모양입니다. 예: 가로장방"
            },
            "도로접면": {
              "type": "string",
              "description": "도로에 닿은 형태입니다. 예: 광대로한면"
            },
            "기준일자": {
              "type": "string"
            }
          },
          "description": "기준연도의 토지특성입니다. 가져오지 못하거나 그해 자료가 없으면 null입니다.",
          "nullable": true
        },
        "공시지가": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "기준연도": {
                "type": "string",
                "description": "공시 기준연도입니다."
              },
              "기준일자": {
                "type": "string"
              },
              "단위면적당가격": {
                "type": "integer",
                "description": "㎡당 개별공시지가(원)입니다. 토지 전체 가격은 필지.면적을 곱해 구합니다."
              }
            }
          },
          "description": "연도별 개별공시지가입니다. 최근 연도부터 정렬하며, 자료가 없는 연도는 빠집니다."
        },
        "토지이용계획": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "용도지역지구구역": {
                "type": "string",
                "description": "지역·지구·구역 이름입니다. 예: 도시지역, 가축사육제한구역"
              },
              "저촉여부": {
                "type": "string",
                "description": "필지가 그 구역에 포함·저촉되는지 표기입니다. 예: 포함, 저촉, 접합"
              },
              "근거법령": {
                "type": "string"
              },
              "기준일자": {
                "type": "string"
              }
            }
          },
          "description": "필지에 걸린 용도지역·지구·구역 목록입니다. 없으면 빈 배열입니다."
        },
        "토지이동이력": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "이동일자": {
                "type": "string",
                "description": "이동이 일어난 날짜입니다."
              },
              "이동사유": {
                "type": "string",
                "description": "이동 사유입니다. 예: 분할, 지목변경"
              },
              "기준일자": {
                "type": "string"
              }
            }
          },
          "description": "분할·합병·지목변경 같은 토지 이동 이력입니다. 없으면 빈 배열입니다."
        }
      }
    },
    "api": {
      "type": "object",
      "properties": {
        "cost": {
          "type": "integer",
          "description": "차감된 포인트입니다. 실패하면 0입니다."
        },
        "success": {
          "type": "boolean",
          "description": "정상 분석 결과는 1, 필지·공시지가를 받지 못한 부분 결과는 0입니다. 0이면 과금되지 않습니다."
        },
        "ms": {
          "type": "integer",
          "description": "처리 시간(밀리초)입니다."
        }
      }
    }
  }
}

```

### 정적 응답 예시

```json

{
  "data": {
    "PNU": "1168010100100120000",
    "소재지": "서울특별시 강남구 역삼동 12",
    "지번": "12",
    "법정동코드": "1168010100",
    "지역코드": "11680",
    "좌표": {
      "x": 127.036,
      "y": 37.5
    },
    "기준연도": "2024",
    "필지": {
      "PNU": "1168010100100120000",
      "법정동코드": "1168010100",
      "법정동": "서울특별시 강남구 역삼동",
      "지번": "12",
      "지목": "대",
      "면적": 330.5,
      "필지구분": "토지대장"
    },
    "토지특성": {
      "지목": "대",
      "면적": 330.5,
      "용도지역_1": "일반상업지역",
      "용도지역_2": "",
      "토지이용상황": "상업용",
      "지형고저": "평지",
      "지형형상": "가로장방",
      "도로접면": "광대로한면",
      "기준일자": "2024-07-31"
    },
    "공시지가": [
      {
        "기준연도": "2024",
        "기준일자": "2024-05-31",
        "단위면적당가격": 52000000
      },
      {
        "기준연도": "2023",
        "기준일자": "2023-05-31",
        "단위면적당가격": 50100000
      }
    ],
    "토지이용계획": [
      {
        "용도지역지구구역": "일반상업지역",
        "저촉여부": "포함",
        "근거법령": "일반상업지역",
        "기준일자": "2024-08-01"
      }
    ],
    "토지이동이력": [
      {
        "이동일자": "1988-04-12",
        "이동사유": "분할",
        "기준일자": "2024-08-01"
      }
    ]
  },
  "api": {
    "cost": 50,
    "success": true,
    "ms": 5200
  }
}

```

### curl

```curl

curl --fail-with-body --request POST 'https://apick.app/rest/land_info' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'address=서울특별시 강남구 역삼동 12' \
  --form-string 'addrType=parcel' \
  --form-string 'year=2024' \
  --form-string 'priceYears=5'

```

### Node.js (서버 ESM)

```javascript

const form = new FormData();
form.append("address", "서울특별시 강남구 역삼동 12");
form.append("addrType", "parcel");
form.append("year", "2024");
form.append("priceYears", "5");
const response = await fetch("https://apick.app/rest/land_info", {
  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 = [
    ("address", (None, "서울특별시 강남구 역삼동 12")),
    ("addrType", (None, "parcel")),
    ("year", (None, "2024")),
    ("priceYears", (None, "5")),
]
response = requests.request("POST", "https://apick.app/rest/land_info",
    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 = [
    'address' => '서울특별시 강남구 역삼동 12',
    'addrType' => 'parcel',
    'year' => '2024',
    'priceYears' => '5',
];
$curl = curl_init('https://apick.app/rest/land_info');
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);

```

## 사용 예시 1. 주소로 필지 종합정보 조회

토지 매물 화면에 지목·면적·용도지역·공시지가를 한 번에 보여 줄 때 씁니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/land_info' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'year=2024' \
  --form-string 'priceYears=5' \
  --form-string 'address=서울특별시 강남구 역삼동 12' \
  --form-string 'addrType=parcel'

```

- `data.PNU`를 저장해 두면 다음부터 주소 없이 `pnu`로 더 빠르게 조회할 수 있습니다.

- 토지 전체 공시가격은 `data.공시지가[0].단위면적당가격` × `data.필지.면적`으로 계산합니다.

## 사용 예시 2. 공시지가 5년 추이

지가 변동을 그래프로 보여 줄 때 `priceYears=5`로 최근 5년 공시지가를 받습니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/land_info' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'addrType=parcel' \
  --form-string 'pnu=1168010100100120000' \
  --form-string 'year=2024' \
  --form-string 'priceYears=5'

```

- `data.공시지가[]`는 최근 연도부터 정렬됩니다. 자료가 없는 연도는 빠지므로 개수가 5보다 적을 수 있습니다.

- `data.토지특성`이 null이면 그 기준연도 자료가 없는 것입니다. `year`를 한 해 낮춰 다시 조회합니다.

## 코드·오류

### 업무 실패 응답

입력 오류·대상 없음·일시 실패는 data.error(사유)와 data.success=0으로 오며 api.cost는 0(과금 없음)입니다. HTTP 상태는 400·404·408·424 중 하나입니다. 입력 오류는 값을 고쳐 다시 요청하고, 408·424는 잠시 후 한 번 다시 시도하세요.

```json

{
  "data": {
    "error": "입력값을 확인해 주세요.",
    "success": 0
  },
  "api": {
    "success": true,
    "cost": 0,
    "ms": 5
  }
}

```

## 상세 기능·요금

이용 전 확인 성공한 조회 한 건당 50P가 차감됩니다. 입력 오류, 주소를 필지로 확정하지 못한 경우, 모든 항목을 가져오지 못한 경우는 data.error로 응답하며 과금되지 않습니다. 필지 기본정보·토지특성·개별공시지가(연도별)·토지이용계획·토지이동이력을 한 번에 돌려줍니다. 소유자·소유권 변동이력은 제공하지 않습니다. 필지 기본정보와 개별공시지가 중 하나라도 받지 못하면 받은 항목만 돌려주고 success 0으로 응답하며 과금하지 않습니다. 이때 받지 못한 항목 이름이 partial.missing에 옵니다. 토지특성·토지이용계획·토지이동이력만 비면 null 또는 빈 배열로 오고 나머지는 정상 응답(과금)입니다. 응답 시간은 보통 8초 이내이고 최대 25초입니다. 요청 시간 제한을 30초 이상으로 잡으세요. 인증키는 서버 환경변수에 보관하고 공개 저장소·웹페이지에 넣지 마세요.

## 상세 요청

항목설정 메서드·주소POST https://apick.app/rest/land_info 인증 헤더Authorization: Bearer — 내 계정의 API 인증키 본문 형식multipart/form-data 위치 지정pnu 또는 address 중 하나는 필요합니다. 둘 다 보내면 pnu를 씁니다. 요청 예시 지번 주소로 최근 5년 공시지가까지 받는 예입니다. 성공 시 과금되는 실제 요청입니다. form-data 전체 예제 보기

## 상세 응답

필드타입설명 data.PNUstring확정된 필지고유번호 19자리입니다. data.소재지string주소로 조회했을 때 확정된 주소입니다. pnu로 조회하면 빈 문자열입니다. data.지번string주소로 조회했을 때의 지번 표기입니다. pnu로 조회하면 빈 문자열입니다. data.법정동코드string법정동코드 10자리입니다. data.지역코드string시군구 단위 지역코드 5자리입니다. 실거래가 조회 등에 그대로 씁니다. pnu로 조회하면 빈 문자열일 수 있습니다. data.좌표object경위도 좌표(x 경도, y 위도)입니다. pnu로 조회하면 null입니다. data.기준연도string실제로 적용된 기준연도입니다. data.필지object필지 기본정보입니다. 가져오지 못하면 null입니다. data.필지.지목string지목 이름입니다. 예: 대, 전, 임야 data.필지.면적number토지 면적(㎡)입니다. 값이 없으면 null입니다. data.필지.필지구분string대장 구분 표기입니다. 예: 토지대장, 임야대장 data.필지.법정동string법정동 이름입니다. data.필지.지번string본번-부번 표기입니다. data.토지특성object기준연도의 토지특성입니다. 가져오지 못하거나 그해 자료가 없으면 null입니다. data.토지특성.용도지역_1string첫 번째 용도지역입니다. 예: 제2종일반주거지역 data.토지특성.용도지역_2string두 번째 용도지역입니다. 없으면 빈 문자열입니다. data.토지특성.토지이용상황string실제 이용 상황입니다. 예: 상업용, 단독 data.토지특성.지형고저string지형의 높낮이입니다. 예: 평지 data.토지특성.지형형상string필지 모양입니다. 예: 가로장방 data.토지특성.도로접면string도로에 닿은 형태입니다. 예: 광대로한면 data.공시지가[]array연도별 개별공시지가입니다. 최근 연도부터 정렬하며, 자료가 없는 연도는 빠집니다. data.공시지가[].기준연도string공시 기준연도입니다. data.공시지가[].단위면적당가격number㎡당 개별공시지가(원)입니다. 토지 전체 가격은 필지.면적을 곱해 구합니다. data.토지이용계획[]array필지에 걸린 용도지역·지구·구역 목록입니다. 없으면 빈 배열입니다. data.토지이용계획[].용도지역지구구역string지역·지구·구역 이름입니다. 예: 도시지역, 가축사육제한구역 data.토지이용계획[].저촉여부string필지가 그 구역에 포함·저촉되는지 표기입니다. 예: 포함, 저촉, 접합 data.토지이동이력[]array분할·합병·지목변경 같은 토지 이동 이력입니다. 없으면 빈 배열입니다. data.토지이동이력[].이동일자string이동이 일어난 날짜입니다. data.토지이동이력[].이동사유string이동 사유입니다. 예: 분할, 지목변경 successinteger정상 분석 결과는 1, 필지·공시지가를 받지 못한 부분 결과는 0입니다. 0이면 과금되지 않습니다. partial.missingarray부분 결과일 때 받지 못한 항목 이름 목록입니다. 정상 응답에는 없습니다. api.costinteger차감된 포인트입니다. 실패하면 0입니다. api.msinteger처리 시간(밀리초)입니다. 각 객체의 기준일자는 그 항목이 마지막으로 갱신된 날짜입니다. 값은 받은 표기 그대로이므로 형식이 항목마다 다를 수 있습니다. { "data": { "PNU": "1168010100100120000", "소재지": "서울특별시 강남구 역삼동 12", "지번": "12", "법정동코드": "1168010100", "지역코드": "11680", "좌표": { "x": 127.0360, "y": 37.5000 }, "기준연도": "2024", "필지": { "PNU": "1168010100100120000", "법정동코드": "1168010100", "법정동": "서울특별시 강남구 역삼동", "지번": "12", "지목": "대", "면적": 330.5, "필지구분": "토지대장" }, "토지특성": { "지목": "대", "면적": 330.5, "용도지역_1": "일반상업지역", "용도지역_2": "", "토지이용상황": "상업용", "지형고저": "평지", "지형형상": "가로장방", "도로접면": "광대로한면", "기준일자": "2024-07-31" }, "공시지가": [ { "기준연도": "2024", "기준일자": "2024-05-31", "단위면적당가격": 52000000 }, { "기준연도": "2023", "기준일자": "2023-05-31", "단위면적당가격": 50100000 } ], "토지이용계획": [ { "용도지역지구구역": "일반상업지역", "저촉여부": "포함", "근거법령": "일반상업지역", "기준일자": "2024-08-01" } ], "토지이동이력": [ { "이동일자": "1988-04-12", "이동사유": "분할", "기준일자": "2024-08-01" } ] }, "api": { "cost": 50, "success": true, "ms": 5200 } }

## 상세 코드·정책

오류와 복구 아래 경우는 data.error로 응답하며 과금되지 않습니다(api.cost 0). 실패 응답은 HTTP 4xx 상태 코드와 함께 올 수 있으니 상태 코드만으로 판단하지 말고 본문의 data.error를 읽으세요. data.error원인해결 [pnu 또는 address] 입력 항목이 잘못됐습니다.pnu와 address가 모두 없습니다.둘 중 하나를 보냅니다. [pnu] 19자리 필지고유번호가 필요합니다.pnu의 숫자가 19자리가 아닙니다.19자리를 확인하거나 address로 조회합니다. [address] 입력 항목이 잘못됐습니다.주소가 200자를 넘습니다.시·도부터 번지까지만 보냅니다. [year] 기준연도가 잘못됐습니다. ex) 20244자리가 아니거나 1990년~올해 범위를 벗어났습니다.올해 이하 4자리 연도로 보내거나 생략합니다. [priceYears] 1~5 사이 값이 필요합니다.이력 연수가 범위를 벗어났습니다.1~5 사이 정수로 보냅니다. 주소 유형이 잘못됐습니다.addrType이 허용값에 없습니다.parcel·road 중 하나로 보내거나 생략합니다. 주소 또는 PNU(19자리)가 필요합니다.address가 공백뿐입니다.주소를 채우거나 pnu로 보냅니다. 해당 주소의 필지를 찾지 못했습니다.주소에 해당하는 필지가 없습니다.번지까지 적었는지, 지번·도로명 유형이 맞는지(addrType) 확인합니다. 주소·필지 정보를 가져오지 못했습니다.주소를 필지로 바꾸는 단계가 일시적으로 실패했습니다.잠시 후 다시 요청하거나 pnu로 조회합니다. 필지 정보를 가져오지 못했습니다.모든 항목을 가져오지 못했습니다.잠시 후 같은 요청을 다시 보냅니다.

## 상세 예제

호출 예시 같은 요청을 JavaScript와 Python으로 옮긴 예시입니다. 키는 환경변수 APICK_API_KEY 에서 읽습니다. JavaScript 예시 form-data 전체 예제 보기 Python 예시 form-data 전체 예제 보기
