openapi

Contents

openapi는 3.7.13 버전 이상 부터 제공되며 해당 라이브러리를 추가하여 사용해야 된다.

getAddress

getAddress 는 찾고자 하는 주소의 특정 단어를 2 글자 이상으로 전달하여 검색하고 그 검색 결과를 전달 받는 API 이다.

address 요청 시 필요한 인자 정보는 아래와 같으며 해당 API 에 대한 자세한 세부내용이 필요할 경우는 웹사이트인 도로명주소 안내시스템에서 확인할 수 있다.

NoNameDescriptionsM/O
1keyword검색어M
2pageNo현재 페이지 번호M
3perPage페이지당 출력할 결과 수M
    

Example

var keyword = 'keyword';
var pageNo = 1;
var perPage = 10;

hone.channel.execute('openapi', 'getAddress', [keyword, pageNo, perPage],
   function (addressResult) {
    // TODO
    }, function (e) {
        alert(JSON.stringify(e));
    }
);

Result

{
   "results": {
       "common": {
           "errorMessage": "정상",
           "countPerPage": "10",
           "totalCount": "1",
           "errorCode": "0",
           "currentPage": "1"
        },
       "juso": [{
           "detBdNmList": "B 동,파인에비뉴",
           "engAddr": "100, Eulji-ro, Jung-gu, Seoul",
           "rn": "을지로",
           "emdNm": "을지로 2 가",
           "zipNo": "04551",
           "roadAddrPart2": " (을지로 2 가)",
           "emdNo": "02",
           "sggNm": "중구",
           "jibunAddr": "서울특별시 중구 을지로 2 가 203 파인에비뉴",
           "siNm": "서울특별시",
           "roadAddrPart1": "서울특별시 중구 을지로 100",
           "bdNm": "파인에비뉴",
           "admCd": "1114010500",
           "udrtYn": "0",
           "lnbrMnnm": "203",
           "roadAddr": "서울특별시 중구 을지로 100 (을지로 2 가)",
           "lnbrSlno": "0",
           "buldMnnm": "100",
           "bdKdcd": "0",
           "liNm": "",
           "rnMgtSn": "111403101006",
           "mtYn": "0",
           "bdMgtSn": "1114010500101450000000001",
           "buldSlno": "0"
        }]
    }
}

Table. address 오류 메시지

메시지조치방법
시스템에러도로명주소 도움센터로 문의 하기
승인되지 않은 키 입니다.정확한 승인 키를 입력하세요 (검색 API 승인키 사용불가)
정상적인 경로로 접속하시기 바랍니다.요청변수 중 returnUrl 항목이 없습니다. 요청 변수를 다시 확인하세요
검색어가 입력되지 않았습니다.검색 어를 입력해주세요
주소를 상세히 입력해 주시기 바랍니다.시도 명으로 검색이 불가 합니다.
검색 어는 두 글자 이상 입력되어야 합니다.한 글자만으로는 검색이 불가합니다.
검색 어는 문자와 숫자 같이 입력되어야 합니다.숫자만으로는 검색이 불가합니다.
검색어가 너무 깁니다. (한글 40 자 영문, 숫자 80 자 이하)80 글자를 초과하는 검색 어는 검색이 불가합니다.
검색어에 너무 긴 숫자가 포함되어 있습니다.10 자리를 초과하는 숫자가 포함된 검색 어는 검색이 불가합니다.
특수문자 + 숫자만으로는 검색이 불가능 합니다.특수문자와 숫자만으로 이루어진 검색 어는 검색이 불가합니다.
  

Table. 주소항목 설명

출력변수명타입필수여부설명
roadFullAddr String Y  전체 도로명 주소
roadAddrPart1 String Y  도로명 주소 (참고항목 제외)
roadAddrPart2 String N  도로명 주소 (참고항목 제외)
jibunAddr String Y  지번주소
engAddrString Y  도로명 주소 (영문)
zipNo String Y  우편번호
addrDetail String N  고객 입력 상세 주소
admCd String Y  행정구역코드
rnMgtSn String Y  도로명코드
bdMgtSn String Y  건물관리번호
detBdNmList String N  상세건물명
bdNm String N  건물명
bdKdcd String N  공동주택 여부 (1:공통주택, 0: 비공동주택)
siNm String Y  시도명
sggNm String Y  시군구명
emdNm String Y  읍면동명
liNm String N  법정리명
rn String Y  도로명
udrtYn String Y  지하여부 (0: 지상, 1: 지하)
buldMnnm Number Y  건물본번
buldSlno Number Y  건물부번
mtYn String Y  산 여부 (0: 대지, 1: 산)
lnbrMnnm Number Y  지번본번 (번지)
lnbrSlno Number Y  지번부번 (호)
emdNo String Y  읍/면/동 일련번호
    

getWeather

Weather 는 GPS 의 위도 / 경도 정보를 전달하여 해당 위치의 날씨 정보를 검색해 그 결과를 전달 받는 API 이다.

Weather 요청 시 필요한 인자는 아래와 같으며 인자에 대한 세부 내용은 관련 웹 페이지인 동네예보정보조회서비스에서 확인할 수 있다.

Table. Weather 인자 정보

NoNameDescriptionsM/O
1latitude위도M
2longitude경도M
3pageNo현재 페이지 번호M
4perPage페이지당 출력할 결과 수M
    

Example

var latitude = 40.689217;
var longitude = -74.044479;
var pageNo = 1;
var perPage = 10;

hone.channel.execute('openapi', 'getWeather', [latitude, longitude, pageNo, perPage],
   function (weatherResult) {
    // TODO
    }, function (e) {
        alert(JSON.stringify(e));
    }
);

Result

{
   "response":{
       "header":{
           "resultCode":"0000",
           "resultMsg":"OK"
        },
       "body":{
           "items":{
               "item":[{
                   "baseDate":20151013,
                   "baseTime":1600,
                   "category":"LGT",
                   "nx":55,
                   "ny":127,
                   "obsrValue":0
                }]
            },
           "numOfRows":10,
           "pageNo":1,
           "totalCount":10
        }
    }
}

Table. Weather 결과 정보 

CodeMessageDescriptions
0000성공 
01Application Error  제공기관 서비스 제공 상태가 원활하지 않습니다.
02DB Error  제공기관 서비스 제공 상태가 원활하지 않습니다.
03No Data  데이터 없음 오류
04HTTP Error  제공기관 서비스 제공 상태가 원활하지 않습니다.
05Service Timeout  제공기관 서비스 제공 상태가 원활하지 않습니다.
10Invalid Parameter Error  Open API 요청 시 Service Key 파라 미터가 누락되었습니다.
11필수 요청 파라 미터가 없음  요청 하신 Open API 의 필수 파라 미터가 누락되었습니다.
12해당 오픈 API 서비스가 없거나 폐기됨  Open API 호출 시 URL 이 잘못 됨
20서비스 접근 오류  활용승인이 나지 않은 Open API 호출
22서비스 요청 제한 횟수 초과 에러  일일 활용 건수가 초과 함 (활용건수 증가 필요)
30등록되지 않은 서비스 키  잘못된 서비스 키를 사용하였거나 서비스 키를 URL 인코딩 하지 않음
31기한 만료된 서비스 키  Open API 사용 기간이 만료됨
32등록되지 않은 도메인명 또는 IP 주소  활용 신청한 서버의 IP 와 실제 Open API 호출한 서버가 다름
   

Table. 아이템 항목 설명

항목(영문)항목(국문크기구분샘플설명
baseDate발표일자8120181212발표일
baseTime발표시각610600발표 시간
nx예보지점 x 좌표2059입력한 예보지점 X 좌표
ny예보지점 y 좌표20125입력한 예보지점 Y 좌표
category자료구분코드31LGT자료구분코드
obsrValue실황 값200RN1, T1H, UUU, VVV, WSD 실수로 제공
      

Table. 초 단기 실황 코드 값

항목 값항목 명단위압축비트수
T1H기온°C10
RN11 시간 강수량mm8
SKY하늘 상태코드 값4
UUU동서 바람 성분m/s12
VVV남북 바람 성분m/s12
REH습도%8
PTY강수형태코드 값4
LGT낙뢰코드 값4
VEC풍향010
WSD풍속110
    

Table. 하늘(SKY) 상태 코드 값

코드맑음구름조금구름많음흐림
SKY  1  2  3  4
     

Table. 강수형태 (PTY) 상태 코드 값

코드없음비진눈개비눈
PTY1234
     

Table. 강수량 (RN1, R06) 범주 및 표시 방법 (값)

범주문자열 표시GRIB 저장 값
0.1mm 미만0mm 또는 없음0
0.1mm 이상 1mm 미만1mm 미만1
1mm 이상 5mm 미만14mm5
5mm 이상 10mm 미만59mm10
10mm 이상 20mm 미만1019mm20
20mm 이상 40mm 미만2039mm40
40mm 이상 70mm 미만4069mm70
70mm 이상 70mm 이상100
   

Table. 적설 (S06) 범주 및 표시방법 (값)

범주문자열 표시GRIB 저장 값
0.1cm 미만0cm 또는 없음0
0.1cm 이상 1cm 미만1cm 미만1
1cm 이상 5cm 미만14cm5
5cm 이상 10cm 미만59cm10
10cm 이상 20cm 미만1019cm20
20cm 이상 20cm 이상100
   

Table. 낙뢰코드 (LGT) 정보

코드없음있음
LGT01
   

Table. 풍속 정보

코드+-
UUU동서
VVV북남
 

getAir

getAir 는 주소의 (구) 정보를 전달 받아 해당 구의 공기 질 정보를 반환 한다.

Air 요청 시 필요한 인자는 아래와 같으며 인자에 대한 세부 내용은 관련 웹 페이지인 대기오염정보조회서비스 에서 확인할 수 있다

Table. getAir 인자 정보

NoNameDescriptionsM/O
1keyword주소 (구 정보)M
2pageNo현재 페이지 번호M
3perPage페이지당 출력할 결과 수M
    

Example

var keyword = '을지로';
var pageNo = 1;
var perPage = 10;

hone.channel.execute('openapi', 'getAir', [keyword, pageNo, perPage],
   function (weatherResult) {
       // TODO
    }, function (e) {
        alert(JSON.stringify(e));
    }
);

Result

<response>
   <header>
       <resultCode>00</resultCode>
       <resultMsg>NORMAL SERVICE.</resultMsg>
   </header>
  <body>
       <items>
           <item>
               <dataTime>2018-09-21 14:00</dataTime>
               <mangName>도시대기</mangName> <so2Value>0.002</so2Value>
               <coValue>0.2</coValue>
               <o3Value>0.025</o3Value>
               <no2Value>0.021</no2Value>
               <pm10Value>16</pm10Value>
               <pm10Value24>11</pm10Value24>
               <pm25Value>9</pm25Value>
               <pm25Value24>7</pm25Value24>
               <khaiValue>42</khaiValue>
               <khaiGrade>1</khaiGrade>
               <so2Grade>1</so2Grade>
               <coGrade>1</coGrade>
               <o3Grade>1</o3Grade>
               <no2Grade>1</no2Grade>
               <pm10Grade>1</pm10Grade>
               <pm25Grade>1</pm25Grade>
               <pm10Grade1h>1</pm10Grade1h>
               <pm25Grade1h>1</pm25Grade1h>
           </item>
           <!-- 중략 -->
       </items>
   </body>
</response>

Table. Air 결과 정보 

CodeMessageDescriptions
00성공 
01Application Error제공기관 서비스 제공 상태가 원활하지 않습니다.
02DB Error제공기관 서비스 제공 상태가 원활하지 않습니다.
03No Data데이터 없음 오류
04HTTP Error제공기관 서비스 제공 상태가 원활하지 않습니다.
05Service Timeout제공기관 서비스 제공 상태가 원활하지 않습니다.
10Invalid Parameter ErrorOpen API 요청 시 Service Key 파라 미터가 누락되었습니다.
11필수 요청 파라 미터가 없음요청 하신 Open API 의 필수 파라 미터가 누락되었습니다.
12해당 오픈 API 서비스가 없거나 폐기됨Open API 호출 시 URL 이 잘못 됨
20서비스 접근 오류활용승인이 나지 않은 Open API 호출
22서비스 요청 제한 횟수 초과 에러일일 활용 건수가 초과 함 (활용건수 증가 필요)
30등록되지 않은 서비스 키잘못된 서비스 키를 사용하였거나 서비스 키를 URL 인 코딩 하지 않음
31기한 만료된 서비스 키Open API 사용 기간이 만료됨
32등록되지 않은 도메인 명 또는 IP 주소활용 신청한 서버의 IP 와 실제 Open API 호출한 서버가 다름
   

Table. 아이템 항목 설명

항목(영문)항목(국문)크기구분샘플설명
dataTime 측정일2012018-04- 20 15:00오염도 측정일
mangName측정망 정보101도시대기측정망 정보 (국가배경, 교외대기, 도시대기, 도로변 대기)
so2Value아황산가스 농도1010.007아황산가스 농도 (단위 : ppm)
coValue일산화탄소 농도1010.4일산화탄소 농도 (단위 : ppm)
o3Value오존 농도1010.043오존 농도 (단위 : ppm)
no2Value이산화질소 농도1010.024이산화질소 농도 (단위 : ppm)
pm10Value미세먼지 (PM10) 농도10173미세먼지 (PM10) 농도 (단위 : μg/m&sup3emoticon_wink
pm10Value24미세먼지 (PM10) 24 시간 예측 이동 농도10155미세먼지 (PM10) 24 시간 예측 이동 농도 (단위 : μg/m&sup3emoticon_wink
pm25Value미세먼지 (PM2.5) 농도10173미세먼지 (PM2.5) 농도 (단위 : μg/m&sup3emoticon_wink
pm25Value24미세먼지 (PM2.5) 24 시간 예측 이동 농도10131미세먼지 (PM2.5) 24 시간 예측 이동 농도 (단위 : μg/m&sup3emoticon_wink
khaiValue통합 대기 환경 수치10175통합 대기 환경수치
khaiGrade통합 대기 환경 지수1012통합 대기 환경 지수
so2Grade아황산가스 지수1011아황산가스 지수
coGrade일산화탄소 지수1011일산화탄소 지수
o3Grade오존 지수1012오존 지수
no2Grade이산화질소 지수1011 이산화질소 지수
pm10Grade미세먼지 (PM10) 24 시간 등급1012미세먼지 (PM10) 24 시간 등급자료
pm25Grade미세먼지 (PM2.5) 24 시간 등급1012미세먼지 (PM2.5) 24 시간 등급자료
pm10Grade1h미세먼지 (PM10) 1 시간 등급1012미세먼지 (PM10) 1 시간 등급자료
pm25Grade1h미세먼지 (PM2.5) 1 시간 등급1012미세먼지 (PM2.5) 1 시간 등급자료
      

Table. 항목별 Grade 값의 의미

등급좋음보통나쁨매우 나쁨
Grade1234
     

getSearch

Search 는 지정된 검색 어를 통해 네이버 / 다음 / 구글의 검색엔진을 통해 검색 결과를 화면에 보여주는 API 이며 search 에 필요한 인자는 아래와 같다.

NoNameDescriptionsM/O
1keyword검색어M
2from검색 엔진 (google, naver, daum)M
3windowName검색 결과를 출력할 Web 형태의 윈도우 또는 팝업 윈도우 명M
    

인자가 전달되면 대상이 되는 웹 윈도우에 검색엔진의 결과를 화면에 출력하여 화면에 표현된다.

Example

var keyword = 'keyword';
var from = 'google';
var windowName = 'defaultWebWindow';

hone.channel.execute('openapi', 'getSearch', [keyword, from, windowName],
   function () {
       // TODO
    }, function (e) {
        alert(JSON.stringify(e));
    }
);

Error Code

CodeCauseComment
E11200파라메터 값이 잘못되어 있을 경우 
E11201전달된 액션 값이 알 수 없는 액션일 경우 
E11202검색어가 잘못되어 있을 경우 
E11203전달된 현재 페이지 번호가 빈값인 경우 
E11204페이지당 출력할 결과 수가 잘못되어 있을 경우 
E11205전달된 현재 페이지 번호가 잘못되어 있을 경우 
E11206페이지당 출력할 결과 수가 잘못되어 있을 경우 
E11207검색엔진 값이 잘못되어 있는 경우 
E11208window name이 잘못되어 있는 경우 
E11250실행 중 오류가 발생 되었을 경우 
E11251서버로 부터 전달받은 응답 메시지가 없는 경우 
E11252서버로 부터 전달받은 응답 메시지가 잘못되어 있는 경우 
E11253인증키를 받지 못한 경우 
E11254assets/config/window.json 에 설정해둔 Window 가 존재하지 않는 경우 
E11255윈도우 생성에 실패한 경우 
E11256윈도우 생성 및 이동시 현재 윈도우가 팝업 윈도우인 경우 
E11299알 수 없는 오류가 발생 되었을 경우