[Growspace Studio API 시리즈 #2] 공간정보 상세 호출 & 업데이트, 실무에 바로 쓰는 API 정리

7월 22, 2025

안녕하세요 프리그로우입니다.

“3D 지도에서 특정 장소의 정보를 확인하려면 어떻게 하나요?”,
“장소 이름이나 설명 같은 걸 우리 서비스에 맞게 바꿀 수 있나요?”

이런 질문, 정말 자주 받습니다.

프리그로우는 직접 개발한 GROWSPACE 지도 API를 통해, 디지털 지도의 장소 정보 호출 및 수정까지 가능한 도구를 제공하고 있어요.

이 API는 특히 지도 기반 관제 시스템이나 공간 운영 도구에서 핵심적인 역할을 하죠.

이번 글에서는 장소 상세 정보 호출 및 수정 API 사용법을 소개할게요.

1️⃣ UID로 장소 상세 정보 호출

장소를 클릭했을 때,

그 안에 어떤 정보가 담겨 있어야 할지 고민해본 적 있으신가요?

콘텐츠와 연결된 정보
어떤 카테고리에 속하는지
언제 등록되었고, 언제 수정되었는지

이런 정보는 단순 리스트 API로는 부족합니다.
그래서 바로 이때 필요한 기능이, UID 기반 장소 상세 정보 조회 API입니다.

어떤 상황에서 필요할까요?

이 API는 다음과 같은 상황에서 유용하게 사용됩니다:

3D 전시 안내도나 관광 안내도에서, 방문자가 특정 장소의 상세 정보를 눌러보고 싶을 때
지도 관제 시스템에서 실시간 장소 상태나 콘텐츠 연결 여부를 확인하고자 할 때
CMS나 백오피스에서 장소 콘텐츠 연결 여부나 태그 상태를 확인할 때
공간 정보 조회가 필요할 때 (예: 건물, 층, 방 구분)
디지털 지도에 표시된 안내 정보를 업데이트하거나 사용자 맞춤 콘텐츠를 띄우고자 할 때

실내 3D 지도를 기반으로 공간을 구현하거나, 지도 길찾기/검색에서 필요한 장소 정보를 연결할 때 아주 유용합니다.
특히 관제 시스템에서 상황 모니터링과 데이터 분석이 필요한 경우, 이 API는 매우 강력한 도구가 됩니다.

API 사용 방법

Method : GET
Endpoint : /open-api/v1/place/{id}

요청 시 반드시 placeAreaUid를 파라미터로 넣어야 해요.

이 UID만 있으면, 등록된 장소의 정밀한 속성 정보를 API를 통해 바로 불러올 수 있습니다.

전시장, 매장, 건물 단위의 장소 정보 관리에서 매우 유용합니다.
응답에는 다음과 같은 정보가 포함됩니다.

장소 타입
홍보 이미지
생성일 및 최종 수정일
지원 언어
플레이스 이름
플레이스 상세 설명
카테고리

응답 예시 :

{
"id": 1,
"placeAreaUid": "A01",
"image": {
"id": 11,
"type": "place",
"image": [
{
"id": 11,
"url": "https://firebasestorage.googleapis.com/v0/b/grow-maps-platform.appspot.com/o/project_thumbnail%2Fd6a71758-8d1b-4e92-a434-8f866066454b.webp?alt=media"
}
]
},
"createDate": "2025-07-16 10:49:44",
"updateDate": "2025-07-16",
"trn": [
{
"language": "def",
"name": "Place 1",
"description": "description"
}
],
"category": "Main category",
"subCategory": "Sub category"
}

2️⃣ 장소 정보 수정

“시설 이름이 바뀌었는데, 3D 지도에도 반영해야 해요.”,
“시즌별로 설명이나 태그를 바꾸고 싶어요.”

상황에 따라 장소 정보가 실시간으로 변화하는 환경이라면, 이 기능은 더욱 중요하죠.
이럴 때 필요한 기능이 바로 장소 정보를 직접 수정할 수 있는 API입니다.

어떤 상황에서 필요할까요?

다음과 같은 경우에 이 API를 활용하면 유용합니다.

실시간으로 공간 정보 업데이트가 필요한 시설 안내도나 전시 안내도에 UID 기반으로 특정 장소를 선택해 효율적으로 수정할 때
마케팅 목적에 따라 설명을 다르게 설정하거나, 다국어 콘텐츠를 연결해야 할 때
지도 제작 이후에도 유연하게 관리가 가능한 구조를 만들고자 할 때
관제 시스템에서 이벤트 대응이나 운영 시나리오 전환에 맞춰 공간 데이터를 갱신해야 할 때

API 사용 방법

Method: PUT
Endpoint: /open-api/v1/place/{id}

요청 시 반드시 placeAreaUid를 파라미터로 넣어야 해요.

수정 가능한 필드 :

categoryId : 카테고리
placeAreaUid : 플레이스 uid
imageId : 플레이스 이미지 id
name : 이름
description : 설명
language : 사용 언어/번역 기준 언어
- 최대 4개 언어까지 선택 가능하며, 선택된 언어로 자동 번역하거나 특정 언어로만 제공할 수 있습니다.

{
"categoryId" : 1,
"placeAreaUid" : "B01",
"imageId" : 13,
"trn" : [
{
"language" : "def",
"description" : "description",
"name" : "place name 1"
}
]
}

응답 예시 :

{
"id": 2,
"placeAreaUid": "B01",
"image": {
"id": 13,
"type": "place",
"image": [
{
"id": 12,
"url": "https://…"
}
]
},
"createDate": "2025-07-16 10:49:52",
"updateDate": "2025-07-16",
"trn": [
{
"language": "def",
"name": "place name 1",
"description": "description"
}
],
"category": "Main category",
"subCategory": "Sub category"
}

이제 지도에 표시된 장소 이름과 좌표가 변경되고, 앱 사용자들도 변경된 정보를 확인할 수 있게 됩니다.
운영 중 생기는 수정 요청을 손쉽게 처리할 수 있다는 점에서 장소 데이터 관리 자동화의 핵심 API라고 볼 수 있어요.