Dataset Items API

데이터 아이템 목록 조회, 상세 조회, 주변 검색 엔드포인트입니다.

모든 엔드포인트는 API Key 인증이 필요합니다. 인증 문서를 참고하세요.

GET /v1/datasets/:datasetId/items

데이터셋 내 아이템 목록을 페이지네이션으로 반환합니다.

인증

Authorization: Bearer <API_KEY>

Path 파라미터

파라미터	타입	필수	설명
`datasetId`	`string`	Yes	Dataset UUID 또는 slug

Query 파라미터

파라미터	타입	기본값	설명
`page`	`number`	`1`	페이지 번호
`limit`	`number`	`20`	페이지 크기 (최대 100)
`sort`	`string`	`"name"`	정렬 필드: `name`, `createdAt`, `updatedAt`
`order`	`string`	`"asc"`	정렬 방향: `asc`, `desc`
`administrativeAreaCode`	`string`	—	행정구역 코드 필터
`categoryCode`	`string`	—	카테고리 코드 필터
`parentItemId`	`string`	—	부모 아이템 필터. `"null"` 입력 시 루트 아이템만 반환

성공 응답

HTTP 200 OK

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "datasetId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "경복궁",
      "description": "서울의 대표 궁궐",
      "administrativeAreaCode": "11",
      "categoryCode": "A01",
      "parentItemId": null,
      "streetAddress": "서울특별시 종로구 사직로 161",
      "addressRegion": null,
      "addressLocality": null,
      "postalCode": null,
      "roadAddress": null,
      "jibunAddress": null,
      "latitude": "37.5796",
      "longitude": "126.9770",
      "thumbnailUrl": null,
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 134
  }
}

에러 응답

HTTP 상태	에러 코드	설명
400	`VALIDATION_FAILED`	limit이 100 초과 등 잘못된 파라미터
401	`UNAUTHORIZED`	인증 실패
403	`DATASET_ACCESS_DENIED`	접근 권한 없음
404	`NOT_FOUND`	데이터셋 없음

GET /v1/dataset-items/:itemId

데이터 아이템 상세 정보를 이미지와 함께 반환합니다.

인증

Authorization: Bearer <API_KEY>

Path 파라미터

파라미터	타입	필수	설명
`itemId`	`string`	Yes	Dataset item UUID

성공 응답

HTTP 200 OK

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "datasetId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "경복궁",
    "description": "서울의 대표 궁궐",
    "administrativeAreaCode": "11",
    "categoryCode": "A01",
    "parentItemId": null,
    "streetAddress": "서울특별시 종로구 사직로 161",
    "addressRegion": null,
    "addressLocality": null,
    "postalCode": null,
    "roadAddress": null,
    "jibunAddress": null,
    "latitude": "37.5796",
    "longitude": "126.9770",
    "thumbnailUrl": null,
    "contactName": "경복궁관리소",
    "telephone": "02-3700-3900",
    "email": null,
    "url": "http://www.royalpalace.go.kr",
    "openingHours": null,
    "extraAttributes": {},
    "dataset": {
      "slug": "tourist-spots",
      "name": "관광지"
    },
    "images": [
      {
        "id": "img-uuid",
        "originalUrl": "https://cdn.example.com/images/original.jpg",
        "cdnUrl": "https://cdn.example.com/images/cdn.jpg",
        "thumbnailSmallUrl": "https://cdn.example.com/images/small.webp",
        "thumbnailMediumUrl": "https://cdn.example.com/images/medium.webp",
        "thumbnailLargeUrl": "https://cdn.example.com/images/large.webp",
        "altText": "경복궁 전경",
        "sortOrder": 0,
        "isPrimary": true
      }
    ],
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-01-01T00:00:00.000Z"
  },
  "meta": {}
}

에러 응답

HTTP 상태	에러 코드	설명
401	`UNAUTHORIZED`	인증 실패
403	`DATASET_ACCESS_DENIED`	접근 권한 없음
404	`NOT_FOUND`	아이템 없음

GET /v1/dataset-items/nearby

지리 좌표 기준으로 주변 아이템을 거리순으로 반환합니다.

인증

Authorization: Bearer <API_KEY>

Query 파라미터

파라미터	타입	필수	기본값	설명
`latitude`	`number`	Yes	—	위도
`longitude`	`number`	Yes	—	경도
`radius`	`number`	No	`1000`	검색 반경 (미터, 1~50000)
`datasetId`	`string`	No	—	특정 데이터셋으로 필터링
`page`	`number`	No	`1`	페이지 번호
`limit`	`number`	No	`20`	페이지 크기 (최대 100)

성공 응답

HTTP 200 OK

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "datasetId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "경복궁",
      "description": "서울의 대표 궁궐",
      "administrativeAreaCode": "11",
      "categoryCode": "A01",
      "streetAddress": "서울특별시 종로구 사직로 161",
      "addressRegion": null,
      "addressLocality": null,
      "postalCode": null,
      "roadAddress": null,
      "jibunAddress": null,
      "latitude": "37.5796",
      "longitude": "126.9770",
      "thumbnailUrl": null,
      "url": "http://www.royalpalace.go.kr",
      "openingHours": null,
      "distance": 350,
      "createdAt": "2025-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 8
  }
}

추가 응답 필드

필드	타입	설명
`distance`	`number`	검색 좌표로부터의 거리 (미터)

에러 응답

HTTP 상태	에러 코드	설명
400	`VALIDATION_FAILED`	좌표 또는 반경 값이 유효하지 않음
401	`UNAUTHORIZED`	인증 실패