- 데이터스페이스 API 는 HTTP Basic 인증방식을 사용합니다.
- HTTPS 통신과 TLS 버전 1.2 이상만 지원합니다.
Space ID, API 인증키가 필수값으로 요구됩니다.
Space ID: ‘데이터스페이스’당 1개의 Space ID가 자동으로 발급되어, 별도의 발급 절차가 필요하지 않습니다. 데이터스페이스에 소속된 계정이라면 누구나 조회할 수 있습니다.
API 인증키: 발급 이후 조회할 수 있으며, 발급 및 재발급은 ‘Developer’ 권한을 가진 계정만 수행할 수 있습니다.
데이터스페이스에 로그인 후, [설정 > 연동 > API] 메뉴에 접근하여 조회 및 복사하실 수 있습니다.
로그인 후에도 [API 키] 메뉴에 접근할 수 없다면, '데이터스페이스’에 멤버로 등록되었는지 확인해보세요.
데이터스페이스의 모든 API는 HTTP Authorization header 에 Basic <crendentials>을 추가해서 요청하도록 설계되어 있습니다.
Space ID 와 API 인증키 사이에 : (콜론)을 추가하고 base64(No Padding)로 인코딩하세요.
credentials = base64({Space ID}:{API 인증키})
인코딩된 값을 API 의 Authorization header 를 다음과 같이 설정하세요.
Authorization: Basic base64({Space ID}:{API 인증키})
아래와 같은 형태로 API 요청이 가능합니다.
GET /v3/surveys/... HTTP/1.1
Authorization: Basic <credentials>
설문 목록 조회
설문 목록을 조회합니다. 설문에 속한 수집그룹들의 상태에 따른 필터링이 가능합니다.
필터를 지정하지 않으면 모든 설문을 조회하고, RUNNING은 현재 진행중인 수집그룹이 있는 설문만 조회합니다.
설문 ID 와 설문 제목, 그리고 생성일자 및 최종 수정일자를 조회할 수 있습니다. 생성일 역순으로 최대 100 건씩 조회합니다.
Authorizations:
query Parameters
| collectGroupStatus | string Value: "RUNNING" |
| size | number Example: size=100 한 번에 조회할 개수 (별도로 지정하지 않으면 100, 최대 100) |
| offset | string Example: offset=a01h1mzpact2df4gjfgq865f1gx response 에서 받은 offset 값을 넣어서 다음 페이지의 설문을 조회할 수 있습니다. |
Responses
Response samples
- 200
- 400
- 500
{- "surveys": [
- {
- "surveyId": "a01hb7vt01vpahrwjyxgd28sf3a",
- "label": "생활 관련 조사",
- "createdAt": "2023-10-02T00:00:00",
- "updatedAt": "2023-10-03T00:00:00"
}
], - "offset": "a01h1mzpact2df4gjfgq865f1gx"
}설문 정보 조회
설문 ID(surveyId) 를 통해 설문 정보를 조회합니다.
Authorizations:
path Parameters
| surveyId required | string Example: a01hb7vt01vpahrwjyxgd28sf3a |
Responses
Response samples
- 200
- 400
- 500
{- "surveyId": "a01hb7vt01vpahrwjyxgd28sf3a",
- "label": "생활 관련 조사",
- "questions": [
- {
- "name": "Q1",
- "type": "SingleChoice",
- "label": "<p>거주하시는 집의 형태는 다음 중 어디에 해당하나요?</p>",
- "options": [
- {
- "name": "1",
- "label": "<p>1번 보기</p>"
}
]
}
], - "embeddedData": [
- {
- "name": "parameter_UID",
- "label": "응답자 고유 식별키"
}, - {
- "name": "profile_1139405",
- "label": "직급"
}
], - "blocks": [
- {
- "name": "B1",
- "label": "새 블록",
- "questions": [
- "Q1",
- "Q2",
- "Q3"
]
}
], - "collectGroups": [
- {
- "collectGroupId": "a01h94kt4fyzmp64h40gzyvrjj7",
- "label": "기본 링크 수집그룹",
- "state": "READY"
}
], - "createdAt": "2023-10-02T00:00:00",
- "updatedAt": "2023-10-03T00:00:00"
}수집그룹 목록 조회
설문 내 모든 수집그룹들의 정보를 조회합니다.
Authorizations:
path Parameters
| surveyId required | string Example: a01hb7vt01vpahrwjyxgd28sf3a |
Responses
Response samples
- 200
- 400
- 500
[- {
- "collectGroupId": "a01h94kt4fyzmp64h40gzyvrjj7",
- "surveyId": "a01hb7vt01vpahrwjyxgd28sf3a",
- "label": "기본 링크 수집그룹",
- "isUsingHmac": false,
- "channel": "PUBLIC_LINK",
- "state": "READY"
}
]수집그룹 정보 조회
수집그룹 ID(collectGroupId) 를 통해 수집그룹 정보를 조회합니다.
Authorizations:
path Parameters
| collectGroupId required | string |
Responses
Response samples
- 200
- 400
- 500
{- "collectGroupId": "a01h94kt4fyzmp64h40gzyvrjj7",
- "surveyId": "a01hb7vt01vpahrwjyxgd28sf3a",
- "label": "기본 링크 수집그룹",
- "channel": "PUBLIC_LINK",
- "state": "READY",
- "targetCnt": 100,
- "startedAt": "2023-10-04T00:00:00",
- "completedAt": "2023-10-10T00:00:00",
- "isUsingHmac": false,
- "createdAt": "2023-10-02T00:00:00",
- "updatedAt": "2023-10-03T00:00:00",
}응답 조회
설문 ID 를 받고, 해당 설문에 대한 응답을 조회합니다. offset 기준으로 최대 1000건의 응답씩 응답 역순으로 조회할 수 있습니다.
Authorizations:
path Parameters
| surveyId required | string Example: a01hb7vt01vpahrwjyxgd28sf3a |
query Parameters
| startDateTime | string <date-time> Example: startDateTime=2020-01-01T00:00:00 응답 제출시각 기준으로 조회할 때 범위 시작 시각입니다. (해당 시각 미포함) |
| endDateTime | string <date-time> Example: endDateTime=2020-01-02T00:00:00 응답 제출시각 기준으로 조회할 때 범위 종료 시각입니다. (해당 시각 포함) |
| variables | string Example: variables=Q1,q2,Q10_1 변수들 중 특정 변수들만 받고 싶을 경우 사용합니다. (대소문자는 구분하지 않습니다.) |
| embeddedData | string Example: embeddedData=parameter_uid,profile_1139405 Embedded data들 중 특정 Embedded data들만 받고 싶을 경우 사용합니다. (대소문자는 구분하지 않습니다.) |
| size | number Example: size=1000 한 번에 조회할 개수 (별도로 지정하지 않으면 1000, 최대 1000) |
| offset | string Example: offset=id_xa5xcrhc response 에서 받은 offset 값을 넣어서 다음 페이지의 응답을 조회할 수 있습니다. |
Responses
Response samples
- 200
- 400
- 500
{- "responses": [
- {
- "parameterUid": "47d5c15",
- "responseId": "id_ijkdbuh4",
- "serial": "aLACT7Q8Key9C",
- "collectGroupId": "a01h94kt4fyzmp64h40gzyvrjj7",
- "completedStatus": "COMPLETED",
- "startedAt": "2023-10-02T12:00:00",
- "finishedAt": "2023-10-02T12:10:00",
- "embeddedData": [
- {
- "name": "parameter_UID",
- "value": "xch123",
- "valueLabel": "응답자 고유 식별키"
}
], - "variables": [
- {
- "name": "Q1",
- "type": "MULTI_SELECT",
- "label": "<p>좋아하는 것은?</p>",
- "options": [
- {
- "value": "1",
- "valueLabel": "<p>1번 보기</p>"
}, - {
- "value": "2",
- "valueLabel": "<p>기타(직접 입력)</p>"
}
], - "answer": [
- {
- "value": "2",
- "etcValue": "기타 응답입니다."
}
]
}
]
}
], - "offset": "id_xa5xcrhc"
}응답 메타데이터 조회
설문 ID 를 받고, 해당 설문에 대한 응답의 메타데이터를 조회합니다. offset 기준으로 최대 1000건의 응답씩 응답 역순으로 조회할 수 있습니다.
Authorizations:
path Parameters
| surveyId required | string Example: a01hb7vt01vpahrwjyxgd28sf3a |
query Parameters
| startDateTime | string <date-time> Example: startDateTime=2020-01-01T00:00:00 응답 제출시각 기준으로 조회할 때 범위 시작 시각입니다. (해당 시각 미포함) |
| endDateTime | string <date-time> Example: endDateTime=2020-01-02T00:00:00 응답 제출시각 기준으로 조회할 때 범위 종료 시각입니다. (해당 시각 포함) |
| size | number Example: size=1000 한 번에 조회할 개수 (별도로 지정하지 않으면 1000, 최대 1000) |
| offset | string Example: offset=id_xa5xcrhc response 에서 받은 offset 값을 넣어서 다음 페이지의 응답 메타데이터를 조회할 수 있습니다. |
Responses
Response samples
- 200
- 400
- 500
{- "responses": [
- {
- "parameterUid": "47d5c15",
- "responseId": "id_ijkdbuh4",
- "serial": "aLACT7Q8Key9C",
- "collectGroupId": "a01h94kt4fyzmp64h40gzyvrjj7",
- "completedStatus": "COMPLETED",
- "startedAt": "2023-10-02T12:00:00",
- "finishedAt": "2023-10-02T12:10:00"
}
], - "offset": "id_xa5xcrhc"
}