Postcodify는 오픈소스로 제공하는 공식 jQuery 플러그인뿐 아니라, API 서버에 HTTP 요청을 보낼 수 있는 프로그램이라면 어디서나 사용이 가능합니다. PC 또는 모바일 어플리케이션, 서버 프로그램 등에 도로명주소 검색 기능이 필요하다면 아래의 내용을 참고하여 개발하시기 바랍니다.
주소를 검색하려면 아래와 같은 형식의 주소로 HTTP GET 요청을 보내야 합니다.
https://api.poesis.kr/post/search.php?q=검색어&v=버전&ref=도메인
검색어의 길이는 3~80글자여야 합니다. (바이트가 아니라 글자수 기준입니다.)
문자셋은 반드시 UTF-8을 사용해야 합니다. EUC-KR 지원이 필요한 경우 검색서버를 직접 구축하고 소스를 수정하여 사용하십시오.
한글과 특수문자는 %ED%95%9C와 같은 형태로 인코딩하고, 공백은 + 또는 %20으로 표기해야 합니다.
(PHP의 urlencode, 자바스크립트의 encodeURIComponent, 자바의 URLEncoder.encode 참고)
공식 jQuery 플러그인을 사용하지 않을 경우, 버전은 반드시 아래의 두 가지 중 하나의 형식으로 지정해 주십시오.
Postcodify 1.8~2.5 버전의 데이터 포맷을 원하시는 경우:
1.9.0-프로그램이름
Postcodify 3.0 이후 버전의 데이터 포맷을 원하시는 경우:
3.0.0-프로그램이름
프로그램 이름은 영문 소문자(a-z), 숫자(0-9), 마침표(.), 하이픈(-), 밑줄(_) 문자만으로 이루어져야 하며,
다른 프로그램을 사칭하거나 다른 프로그램으로 오해할 소지가 있는 이름을 사용해서는 안 됩니다.
모바일 어플리케이션의 경우 com.개발사.어플명과 같은 패키지명을 그대로 사용하시기를 권장합니다.
무료 API 서버는 버전에 따라 다른 포맷으로 데이터를 반환합니다.
버전이 1.9.0- 또는 3.0.0-으로 시작하지 않거나, 프로그램 이름 표기법을 지키지 않거나,
공식 jQuery 플러그인의 버전을 흉내낼 경우,
무료 API 서버의 운영 정책 변화에 따라 갑자기 검색 서비스가 중단되거나
반환 데이터의 포맷이 달라질 수 있으니 주의하시기 바랍니다.
검색서버를 직접 구축한 경우에도 버전에 따라 데이터 반환 형태가 달라질 수 있으니, 어플리케이션을 업데이트할 때마다 매번 버전을 변경하지 말고 최소한 앞부분은 일정하게 유지해 주시기 바랍니다.
무료 API 서버를 사용하려면 반드시 유효한 도메인을 지정해야 합니다. 도메인을 지정하지 않거나, 프로그램과 무관한 타인의 도메인을 도용할 경우 일일 검색수 제한이 아주 낮게 적용되거나 검색이 차단될 수 있으니 주의하십시오.
일반적인 웹페이지에서 공식 jQuery 플러그인을 사용하면 현재 페이지의 도메인을 자동으로 인식합니다.
PhoneGap과 같이 도메인이 없는 웹페이지에서 공식 jQuery 플러그인을 사용하는 경우,
overrideDomain 옵션을 사용하여 도메인을 수동으로 지정해 주십시오.
(이 옵션의 사용법은 매뉴얼을 참고하시면 됩니다.)
도메인은 아래에 해당하는 것을 사용하시면 됩니다.
프로그램이름.local 사용전체 주소가 아닌 도메인만을 기준으로 일일 검색수 제한을 적용하므로
cafe.daum.net, blog.naver.com처럼 불특정 다수를 대상으로 한 무료 서비스 도메인은 인정하지 않으며,
서브도메인을 여러 개 생성하여 사용할 경우에도 하나의 도메인으로 취급합니다.
단, 홈페이지명.cafe24.com처럼 웹호스팅 업체에서 정식으로 부여하는 서브도메인은 예외입니다.
도메인별 검색수 제한 정책에 대한 자세한 내용은 매뉴얼을 참고하시기 바랍니다.
검색서버를 직접 구축한 경우에는 도메인을 지정하지 않아도 무방합니다.
반환 데이터 포맷은 JSON이며, 문자셋은 UTF-8입니다.
정확한 스키마는 소스코드를 참고하시기 바랍니다.
모바일 플랫폼의 “웹뷰” 기능을 사용하거나 PC용 프로그램에서 웹 브라우저를 내장하여 화면을 표시하는 경우,
웹 페이지와 유사한 환경이므로 공식 jQuery 플러그인을 사용할 수도 있습니다.
그러나 공식 jQuery 플러그인은 일반적인 웹 브라우저 환경을 대상으로 제작되었으므로
도메인이 없거나 특수한 보안 정책의 적용을 받는 환경에서는
CORS를 비롯한 몇몇 기능이 정상적으로 동작하지 않을 수도 있습니다.
만약 CORS가 문제를 일으킨다면 useCors 옵션을 false로 바꾸어 테스트해 보시기 바랍니다.
도메인을 직접 지정하여 사용할 경우, Referer 헤더가 전송되지 않도록 조치해야 합니다.
지정한 도메인과 Referer 헤더의 URL이 일치하지 않을 경우 검색이 차단될 수 있습니다.
무료 API 서버가 사용하는 CloudFlare CDN의 정책에 따라, 2014년 11월부터 보안서버(HTTPS) 사용시 SSLv3 프로토콜은 지원하지 않습니다. HTTPS를 사용하여 API 요청을 수행하려면 개발툴이 TLSv1 또는 상위 프로토콜을 지원하는지 확인해 주십시오. 아주 오래된 버전의 운영체제나 개발툴은 TLSv1을 지원하지 않을 수도 있습니다.
공식 jQuery 플러그인을 사용하지 않는다면 무료 API 메인서버에 연결할 수 없거나 서버가 오류를 반환할 경우 백업서버를 사용하는 루틴을 직접 개발해야 합니다.
무료 API 서버의 일일 검색수 제한 정책은 클라이언트단에서 직접 API 요청을 수행한다고 가정하고 있으므로, 클라이언트를 대신하여 서버단에서 API 요청을 수행할 경우 서버의 IP 주소가 일일 검색수 제한을 초과할 수 있습니다. 이런 경우에는 가능하면 검색서버를 직접 구축하여 사용하시고, 불가피한 경우 해당 IP 주소의 검색수 제한 조정을 요청하여 주시기 바랍니다.