SubKorea > 오픈 API > Google Ajax Search API > 
 

개발자 가이드

Google AJAX 검색 API는 웹 페이지 및 다른 웹 응용프로그램에 Google 검색을 포함할 수 있게 해주는 자바스크립트 라이브러리입니다. Flash 및 다른 비 자바스크립트 환경에서 API는 원시 RESTful 인터페이스 New!를 표시합니다. 이 인터페이스는 대부분의 언어 및 런타임에서 쉽게 처리할 수 있는 JSON 인코딩 검색결과를 반환합니다. 

Google AJAX 검색 API는 많은 Google 서비스(웹 검색, 지역 검색, 동영상 검색, 블로그 검색, 뉴스 검색, 도서 검색 및 이미지 검색)를 통해 인라인 검색을 수행하는 간단한 웹 개체를 제공합니다. 현재 사용자가 콘텐츠(예: 게시판, 블로그)를 만들 수 있도록 웹페이지가 구성된 경우 API는 검색결과를 직접 메시지에 복사할 수 있게 하여 이러한 활동을 지원하도록 구성됩니다. 

이 API는 새로운 API이며, API의 기능 세트는 주로 고객의 적극적인 참여에 의해 결정됩니다. Google AJAX 검색 API 토론 그룹에서 의견을 제출하고 API에 대한 토론에 참여하여 API 및 기능을 구성하는 데 도움을 주시기 바랍니다. 

AJAX 검색 API는 이제 AJAX API 로더를 사용합니다. 이 로더를 사용하면 같은 페이지에서 여러 Google AJAX API를 쉽게 사용할 수 있으며 이러한 API 간에 네임스페이스를 통합합니다. 코드 변경을 원하지 않으면 변경하지 않아도 됩니다. 기존 네임스페이스가 계속 작동합니다. 

추가 정보: 

목차

대상 
소개 
Google AJAX 검색 API의 Hello World 
Google AJAX API 로더 사용 
브라우저 호환성 
API 업데이트 
예 
기본사항 
SearchControl 모드 
Searcher 개체 
Searcher 옵션 
검색결과 저장 
사이트 제한 설정 
검색 컨트롤 콜백 
맞춤검색 양식 
고급 브랜딩 
고급 샘플 
API 개요 
검색결과 스타일 지정New! 
Flash 및 비 자바스크립트 환경New! 
코드조각 
클래스 참조 
문제해결 

대상

이 도움말은 자바스크립트 프로그래밍 및 개체 지향 프로그래밍 개념을 잘 알고 있는 사용자를 대상으로 합니다. 웹에는 사용할 수 있는 자바스크립트 자습서가 많이 있습니다. 

소개

Google AJAX 검색 API의 'Hello, World'

간단한 예를 확인하여 이 API에 대해 자세히 알아볼 수 있습니다. 다음 웹페이지는 'VW GTI'에 대한 인라인 검색결과 모음을 표시합니다. 검색결과에는 지역, 웹, 동영상, 블로그, 뉴스, 이미지, 특허New! 및 도서 검색결과가 포함됩니다.  
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
    <title>Hello World - Google AJAX Search API Sample</title>
    <script src="http://www.google.com/jsapi"
        type="text/javascript"></script>
    <script language="Javascript" type="text/javascript">
    //<![CDATA[
    google.load('search', '1');
    
    function OnLoad() {
      // Create a search control
      var searchControl = new google.search.SearchControl();

      // Add in a full set of searchers
      var localSearch = new google.search.LocalSearch();
      searchControl.addSearcher(localSearch);
      searchControl.addSearcher(new google.search.WebSearch());
      searchControl.addSearcher(new google.search.VideoSearch());
      searchControl.addSearcher(new google.search.BlogSearch());
      searchControl.addSearcher(new google.search.NewsSearch());
      searchControl.addSearcher(new google.search.ImageSearch());
      searchControl.addSearcher(new google.search.BookSearch());
      searchControl.addSearcher(new google.search.PatentSearch());

      // Set the Local Search center point
      localSearch.setCenterPoint("New York, NY");

      // tell the searcher to draw itself and tell it where to attach
      searchControl.draw(document.getElementById("searchcontrol"));

      // execute an inital search
      searchControl.execute("VW GTI");
    }
    google.setOnLoadCallback(OnLoad);

    //]]>
    </script>
  </head>
  <body>
    <div id="searchcontrol">Loading</div>
  </body>
</html>
이 예제를 다운로드하여 편집하고 재생할 수 있습니다. 

웹사이트 내에서 검색 API를 사용하려면 Google AJAX API 로더 URL(http://www.google.com/jsapi)을 포함해야 합니다. 이 라이브러리를 사용하면 google.load('api', 'version')을 통해 여러 가지 API를 로드할 수 있습니다. 여기서 자세한 내용을 배울 수 있습니다. 검색 컨트롤 기능을 사용하기 전에 항상 <script> 태그 내에 이 라이브러리를 포함해야 합니다. 

Google AJAX 검색 API에서 사용하는 기본 개체는 SearchControl의 인스턴스입니다. 이 인스턴스는 해당 개체의 하위로 표시되는 검색 서비스의 모음에서 검색을 조정합니다. 

위의 샘플에서 볼 수 있듯이 LocalSearch, WebSearch, VideoSearch, BlogSearch, NewsSearch, ImageSearch 및 BookSearch 유형의 하위 개체가 addSearcher() 메서드를 사용하여 검색 컨트롤에 추가되고 이러한 searcher 개체는 검색 컨트롤이 작동하는 검색 서비스를 결정합니다. 

검색 컨트롤은 SearchControl draw() 메서드 호출을 통해 웹페이지 내에 자신을 표시합니다. 이 메서드는 사용자의 페이지(DOM 내)에 검색 컨트롤을 바인딩합니다. 기본적으로 검색 컨트롤은 '일직선으로 늘어선' 레이아웃으로 표시되며, '탭 모양' 레이아웃으로 표시하도록 컨트롤을 지정할 수도 있습니다. 이러한 표시 모드에 대해서는 뒤에서 설명합니다. 

탭 모양 레이아웃 옵션 외에도 검색 컨트롤을 사용하여 검색결과 집합에서 '검색 양식'을 쉽게 분리할 수 있습니다. 예를 들어, 페이지 메뉴에 검색 양식을 표시하고, 페이지 가운데에 누적된 결과를 표시하는 것입니다. 

사용자는 검색 컨트롤의 입력란에 검색어를 입력하고 Enter 키를 누르거나, 입력란 오른쪽에 있는 검색 버튼을 클릭하여 검색을 시작합니다. 검색 컨트롤은 요청된 Google 서비스에서 자동으로 동시 검색을 시작합니다. 검색 컨트롤의 execute() 메서드를 호출하고 검색어 인수를 전달하여 검색을 프로그래밍 방식으로 시작할 수도 있습니다. 

Google AJAX API 로더 사용

이제 Google AJAX 검색 API는 Google AJAX API 로더에 완전히 통합되었습니다. 로더를 사용하면 지원되는 모든 Google AJAX API(Google 지도 API 및 Google AJAX 피드 API 포함)에 대해 단일 API 키를 사용하여 모든 API를 로드할 수 있습니다. Google AJAX API 로더는 일반 네임스페이스 스키마를 지정하므로 다른 Google API를 쉽게 함께 사용할 수 있습니다. 이전 네임스페이스 스키마도 계속 지원되므로 기존 응용프로그램을 업데이트할 필요가 없습니다. 

Google AJAX API 로더 사용법은 비교적 간단합니다. 로더를 사용하도록 응용프로그램을 변경하는 과정은 다음과 같습니다. 

  • http://www.google.com/uds에서 AJAX 검색 API를 로드하지 않고 http://www.google.com/jsapi에서 일반 로더를 로드합니다. 아래와 같이 기존 Google AJAX 검색 API 키를 전달할 수 있습니다. 
    • <script type="text/javascript" src="http://www.google.com/jsapi?key=ABCDEFG"></script>
  • 아래와 같이 google.load 메서드를 사용하여 AJAX 검색 API를 로드합니다. google.load 메서드에는 특정 API에 대한 인수와 로드할 버전 번호를 지정합니다. 
    • <script type="text/javascript">
  google.load("search", "1");
</script>
  • 현재 Google AJAX 검색 API에서 사용하는 모든 클래스, 메서드 및 속성에 google.search.* 네임스페이스를 사용하여 G 프리픽스를 이 네임스페이스로 바꿉니다. 예를 들면, Google AJAX API 로더를 사용할 때 google.search.SearchControl 개체는 google.search.SearchControl로 매핑됩니다. 
    • <html>
  <head>
    <script src="http://www.google.com/jsapi?key=ABCDEFG" type="text/javascript"></script>
        <script type="text/javascript">
      google.load("search", "1");

      // Call this function when the page has been loaded
      function initialize() {
            var searchControl = new google.search.SearchControl();
            searchControl.addSearcher(new google.search.WebSearch());
        searchControl.addSearcher(new google.search.NewsSearch());
            searchControl.draw(document.getElementById("searchcontrol"));
      }
          google.setOnLoadCallback(initialize);
        </script>

  </head>
  <body>
        <div id="searchcontrol"></div>
      </body>

</html>
  • GSearch.setOnLoadCallback 대신 google.setOnLoadCallback을 사용하여 문서가 로드된 후 호출될 지정된 핸들러 함수를 등록합니다. 
  • AJAX 검색 API에는 몇 가지 로더 설정 옵션이 있습니다.New! 
    • 동적 로드 - 동적 로드 도움말을 참조하세요. 
    • CSS 로드 안 함 - 기본 CSS를 로드하지 않으려면 "nocss"를 true로 설정하세요. 
      • google.load("search", "1", {"nocss" : true});
    • 이전 네임스페이스 로드 안 함 - 이전 네임스페이스(GSearch, GSearchControl 등)를 로드하지 않으려면 "nooldnames"를 true로 설정하세요. 
      • google.load("search", "1", {"nooldnames" : true});
      참고: 대부분의 샘플은 이전 네임스페이스를 사용하므로 이 설정을 사용하면 제대로 작동하지 않습니다. 이 설정은 네임스페이스가 Google AJAX 검색 API에서 복잡해지기를 원하지 않는 맞춤형 응용프로그램 전용입니다. 
    • 특정 UI 언어 - UI 구성요소(SearchControl, 브랜드 등)에 대한 언어를 지정하여 자동으로 감지되지 않게 하려면 "language"를 en, es, zh-CN, pt-PT 등과 같은 특정 언어 코드로 설정하세요. 
      • google.load("search", "1", {"language" : "en"});
    Google AJAX API 로더 사용에 대한 전체 도움말은 http://code.google.com/intl/ko/apis/ajax/documentation/에서 볼 수 있습니다. 

    브라우저 호환성

    Google AJAX 검색 API는 현재 Firefox 1.5 이상, IE 6 및 Safari, Opera 9 이상을 지원합니다. 

    API 업데이트

    google.load('search', '1.0'); 내의 두 번째 인수에는 API의 예상 버전 레벨(이 경우 버전 '1.0')이 포함됩니다. API의 중요 업데이트를 수행할 때 버전 번호를 올리고 AJAX 검색 API 토론 그룹에 알림을 게시합니다. 이 경우 필수 코드 변경 사항을 기록해 두고 호환되는 경우 URL을 새 버전으로 업데이트하세요. 

    새 버전이 출시되면 Google은 일정 기간 동안(여러 달) 기존 버전과 새 버전을 모두 지원합니다. 이 기간이 만료되면 기존 API를 사용하는 클라이언트 요청은 더 이상 수락되지 않으므로 새 버전이 나오면 즉시 코드를 변경하세요. 

    Google AJAX 검색 API 팀도 버전 업데이트 필요 없이 API를 최신 버그 수정사항과 성능 향상 기능으로 정기적으로 업데이트할 것입니다. 대부분의 경우 이러한 수정사항은 사용자가 알 수 있어야 하지만, 실수로 일부 API 클라이언트를 차단할 수도 있습니다. 이런 문제가 발견되면 AJAX 검색 API 토론 그룹을 통해 알려주세요. 

    예

    참고: 아래의 각 예는 전체 HTML 파일이 아니라 관련 자바스크립트 코드만 표시합니다. 앞에 표시된 기본 HTML 파일에 코드를 연결하거나, 예제 다음에 나오는 링크를 클릭하여 각 예제에 대한 전체 HTML 파일을 다운로드할 수 있습니다. 

    기본사항

    다음 예제(이전 Hello World 코드 샘플 내의 자바스크립트 코드와 동일)에서는 검색 컨트롤을 만들고, 지역 검색, 웹 검색, 동영상, 블로그, 뉴스, 이미지 및 도서 검색에서 검색하도록 검색 컨트롤을 구성한 후 페이지에 배치합니다.  
    // create a search control
var searchControl = new google.search.SearchControl(null);

// add in a full set of searchers
searchControl.addSearcher(new google.search.LocalSearch());
searchControl.addSearcher(new google.search.WebSearch());
searchControl.addSearcher(new google.search.VideoSearch());
searchControl.addSearcher(new google.search.BlogSearch());
searchControl.addSearcher(new google.search.NewsSearch());
searchControl.addSearcher(new google.search.ImageSearch());
searchControl.addSearcher(new google.search.BookSearch());
searchControl.addSearcher(new google.search.PatentSearch());

// tell the searcher to draw itself and tell it where to attach
// Note that an element must exist within the HTML document with id "search_control"
searchControl.draw(document.getElementById("search_control"));
    예제 보기(helloworld.html) 

    SearcherControl 표시 모드

    다양한 표시 모드로 표시되도록 검색 컨트롤을 프로그래밍할 수 있습니다. google.search.DrawOptions 개체는 setDrawMode() 메서드를 통해 이 동작을 제어합니다. 이 메서드는 다음 인수를 사용합니다. 
    • google.search.SearchControl.DRAW_MODE_LINEAR 
    • google.search.SearchControl.DRAW_MODE_TABBED 
    검색 컨트롤 개체의 표시 모드를 실제로 설정하려면 google.search.DrawOptions 개체를 검색 컨트롤의 draw() 메서드로 전달하세요.  
    // create a drawOptions object
var drawOptions = new google.search.DrawOptions();

// tell the searcher to draw itself in linear mode
drawOptions.setDrawMode(google.search.SearchControl.DRAW_MODE_LINEAR);
searchControl.draw(element, drawOptions);
    // tell the searcher to draw itself in tabbed mode
drawOptions.setDrawMode(google.search.SearchControl.DRAW_MODE_TABBED);
searchControl.draw(element, drawOptions);
    예제 보기(tabbed.html) 

    이 메서드를 통해 사용할 수 있는 또 다른 일반 옵션은 검색결과 집합와 '검색 양식'을 분리하는 기능입니다. google.search.DrawOptions 개체는 setSearchFormRoot() 메서드를 통해 이 동작을 제어합니다. 이 메서드는 검색 양식의 컨테이너 역할을 하는 DOM 요소를 사용합니다.  

    // create a drawOptions object
var drawOptions = new google.search.DrawOptions();
drawOptions.setSearchFormRoot(document.getElementById("searchForm"));

searchControl.draw(element, drawOptions);
    예제 보기(searchformroot.html) 

    Searcher 개체

    검색 컨트롤 개체의 addSearcher() 메서드는 검색 컨트롤이 검색할 검색 서비스를 결정합니다. 이 메서드는 서비스 개체를 지정하는 인수와 서비스에 대한 옵션을 지정하는 인수, 이 두 가지 인수를 사용합니다. 다음 searcher 개체(서비스)가 현재 지원됩니다. 
    • google.search.LocalSearch 
    • google.search.WebSearch 
    • google.search.VideoSearch 
    • google.search.BlogSearch 
    • google.search.NewsSearch 
    • google.search.ImageSearch 
    • google.search.BookSearch 
    • google.search.PatentSearchNew! 
    Google AJAX 검색 API는 현재 계속 개선되고 있는 서비스이므로, 시간이 지날수록 지원되는 서비스가 더 많아질 것입니다. 

    google.search.SearcherOptions

    개별 searcher를 검색 컨트롤에 추가할 때 다른 선택적 매개변수인 google.search.SearcherOptions 개체가 각 서비스의 기본 확장 모드를 제어합니다. 이 모드는 웹페이지의 해당 서비스 위치에 검색결과가 표시되는 방식에 영향을 줍니다. 확장 모드는 다음 중 하나가 될 수 있습니다. 
     
    google.search.SearchControl.EXPAND_MODE_OPEN 
    결과가 개체 내에서 가능한 완전히 표시됩니다. 
    google.search.SearchControl.EXPAND_MODE_CLOSED 
    결과가 보기에 표시되지 않으며, 사용자 인터페이스 요소(예: 화살표)를 사용하여 열 수 있습니다. 
    google.search.SearchControl.EXPAND_MODE_PARTIAL 
    결과가 '열린' 확장 모드의 하위 집합으로 표시됩니다. 
    // create a searcher options object
// set up for open expansion mode
// load a searcher with these options
var options = new google.search.SearcherOptions();
options.setExpandMode(google.search.SearchControl.EXPAND_MODE_OPEN);
searchControl.addSearcher(new google.search.WebSearch(), options);

    확장 모드 제어

    다음 예제에서는 각 searcher가 서로 다른 확장 모드에서 작동하는 검색 컨트롤의 사용을 보여줍니다. searcher가 탭 모양 모드로 표시되는 경우에는 확장 모드는 무시됩니다. 이 경우 searcher는 항상 열린 모드로 작동합니다.  
    // local search, partial
options = new google.search.SearcherOptions();
options.setExpandMode(google.search.SearchControl.EXPAND_MODE_PARTIAL);
searchControl.addSearcher(new google.search.LocalSearch(), options);

// web search, open
options = new google.search.SearcherOptions();
options.setExpandMode(google.search.SearchControl.EXPAND_MODE_OPEN);
searchControl.addSearcher(new google.search.WebSearch(), options);
    예제 보기(expandmode.html) 

    검색결과 위치 제어

    일부 응용프로그램에서는 제공된 서비스에 대한 검색결과를 웹페이지의 임의 위치에 표시하도록 지정하는 것이 좋습니다. 이 작동 모드는 서비스의 해당 searcher 개체의 setRoot() 메서드를 사용하여 지원됩니다.  
    // web search, open, alternate root
var options = new google.search.SearcherOptions();
options.setExpandMode(google.search.SearchControl.EXPAND_MODE_OPEN);
options.setRoot(document.getElementById("somewhere_else"));
searchControl.addSearcher(new google.search.WebSearch(), options);
    예제 보기(somewhere-else.html) 

    검색결과 저장

    지금까지 본 샘플은 검색결과를 다른 응용프로그램에 저장하는 기능은 없고 표시용으로만 페이지에 검색결과를 포함하는 데 중점을 두었습니다. 이것은 Google AJAX 검색 API를 사용하는 가장 적합한 방법이기는 하지만 실제 잠재적인 기능을 보여주지는 않습니다. Google AJAX 검색 API를 통해 사용자는 검색결과를 블로그 게시물, 게시판과 같은 콘텐츠 작성 응용프로그램을 통해 다른 사용자에게 배포할 수 있습니다. 

    google.search.SearchControl 개체는 setOnKeepCallback() 메서드를 통해 이 기능을 제공합니다. 이 메서드를 사용하여 응용프로그램에서 사용자가 검색결과 아래에 있는 "복사" 링크를 클릭하여 검색결과를 저장하려고 할 때마다 호출되는 개체와 메서드를 지정합니다. 

    이 링크는 응용프로그램에서 setOnKeepCallback() 메서드를 호출한 경우에만 제공됩니다. 사용자가 링크를 클릭하면 등록된 콜백이 검색결과를 나타내는 GResult 인스턴스를 받습니다. 이 검색결과 개체에는 많은 searcher별 속성과, 전체 검색결과를 나타내는 HTML 요소가 포함된 단일 html 속성이 들어 있습니다. 콜백을 처리하는 가장 간단한 방법은 html 노드를 복제하여 응용프로그램의 DOM에 있는 노드에 첨부하는 것입니다.  

    // establish a keep callback
searchControl.setOnKeepCallback(this, MyKeepHandler);

function MyKeepHandler(result) {
  // clone the result html node
  var node = result.html.cloneNode(true);

  // attach it
  var savedResults = document.getElementById("saved_results");
  savedResults.appendChild(node);
}
    예제 보기(keephandling.html) 

    사이트 제한 설정

    상황에 따라 웹 검색, 뉴스 검색 또는 블로그 검색을 특정 사이트나 블로그로 제한할 수 있습니다. 이와 같은 제한을 적용하게 되면 연관된 검색결과 섹션에 고유한 맞춤 라벨을 설정하거나, 검색결과 섹션에 다른 스타일을 지정하고 싶기도 합니다. 

    이러한 기능은 모두 검색 옵션에서 노출하는 메서드의 조합을 사용하여 지원됩니다. 다음 샘플은 .setUserDefinedLabel(), .setUserDefinedClassSuffix() 및 .setSiteRestriction()의 사용을 보여줍니다. 이 샘플에서 만드는 검색 컨트롤에서는 google.search.WebSearch의 인스턴스 중 하나는 amazon.com의 검색결과만 반환하도록 지정하고, 'Amazon.com'을 검색 섹션 라벨로 사용하며, 이 섹션에 사용자설정 css 스타일의 일부를 적용합니다(굵게 표시된 제목, 오렌지색 담기 버튼 등). google.search.BlogSearch 및 google.search.NewsSearch에 대한 사이트 제한을 보여주는 비슷한 섹션도 표시됩니다.  

    <style type="text/css">
/* customize checkbox for -siteSearch section and
 * set section title and keep label to bold
 */
.gsc-resultsRoot-siteSearch .gsc-keeper {
  background-image : url('../../css/orange_check.gif');
  font-weight : bold;
}
.gsc-resultsRoot-siteSearch .gsc-title { font-weight : bold; }
...

// site restricted web search with custom label
// and class suffix
var siteSearch = new google.search.WebSearch();
siteSearch.setUserDefinedLabel("Amazon.com");
siteSearch.setUserDefinedClassSuffix("siteSearch");
siteSearch.setSiteRestriction("amazon.com");
searchControl.addSearcher(siteSearch);

// site restricted web search using a custom search engine
siteSearch = new google.search.WebSearch();
siteSearch.setUserDefinedLabel("Product Reviews");
siteSearch.setSiteRestriction("000455696194071821846:reviews");
searchControl.addSearcher(siteSearch);
        
    예제 보기(sitesearch.html) 

    검색 컨트롤 콜백

    어떤 상황에서는 검색 컨트롤아 필요한 모든 UI를 제공하므로 검색 컨트롤을 사용하고 싶은 경우가 있지만, 검색결과를 표시하거나 부분적으로 처리해야 합니다. 이 기능이 있지만 UI를 담당하고 있는 google.search.Search 레이어를 고려하는 대신 검색 컨트롤은 한 쌍의 콜백을 제공합니다. 이 콜백을 사용하여 검색 전후에 알림을 요청할 수 있습니다. 지정된 실행 결과는 완료되지 않습니다. 실행 결과는 완료되지 않으므로 직접 코딩하여 교착 상태에 빠지지 않게 하세요. 일반적인 예는 지역 검색결과를 옆에 있는 지도에 연결할 때 이러한 상황이 발생하는 경우입니다. 

    다음 코드조각은 이 기능의 사용을 보여줍니다.  

    searchControl.setSearchCompleteCallback(this, App.prototype.OnSearchComplete);
searchControl.setSearchStartingCallback(this, App.prototype.OnSearchStarting);


App.prototype.OnSearchComplete = function(sc, searcher) {

  // if we have local search results, put them on the map
  if ( searcher.results && searcher.results.length > 0) {
    for (var i = 0; i < searcher.results.length; i++) {
      var result = searcher.results[i];

      // if this is a local search result, then proceed...
      if (result.GsearchResultClass == GlocalSearch.RESULT_CLASS ) {
        ...

App.prototype.OnSearchStarting = function(sc, searcher, query) {
  alert("The Query is: " + query);
  ...
        
    다음 샘플은 이러한 API 사용을 더 완벽하게 보여줍니다. 이 두 개의 콜백을 사용하여 지역 검색결과를 처리한 다음 옆에 있는 지도에 표시하는 방법을 보여줍니다. 예제 보기(sc-callbacks.html) 

    맞춤검색 양식

    google.search.SearchControl을 사용할 때 응용프로그램에서도 통합된 '검색 양식'을 사용할 수 있습니다. 이 양식은 텍스트 입력 요소, 검색 버튼, 지우기 버튼 및 'google 브랜드'를 제공합니다. 응용프로그램에서 검색 컨트롤을 사용하지 않고 대신 원시 google.search.Search 레이어를 사용하는 경우 google.search.SearchForm() 개체가 지정됩니다... 이 개체를 사용하면 검색 컨트롤에 통합된 검색 양식의 장점과 브랜드를 모두 이용할 수 있지만 이 검색 양식은 독립형 개체로 패키지되어 있으므로 동작과 배치를 모두 제어해야 합니다. 

    다음 코드조각은 이 기능의 사용을 보여줍니다.  

    // create a search form without a clear button
// bind form submission to my custom code
var container = document.getElementById("searchFormContainer");
this.searchForm = new google.search.SearchForm(false, container);
this.searchForm.setOnSubmitCallback(this, App.prototype.newSearch);

// called on form submit
App.prototype.newSearch = function(form) {
  if (form.input.value) {
    this.searchControl.execute(form.input.value);
  }
  return false;
}
        
    다음 샘플은 이 개체의 사용을 보여줍니다. 예제 보기(places.html) 

    고급 브랜딩

    google.search.SearchControl 또는 google.search.SearchForm을 사용할 때 일반적으로 사용자에게 'Google 제공' 브랜드가 제공됩니다. 사용자는 사이트에서 제공하는 검색 서비스와 Google을 연결할 수 있습니다. 응용프로그램에서 이러한 양식을 사용하지 않을 경우에도 Google 브랜드를 사용자에게 알리는 것이 중요합니다. google.search.Search.getBranding() 메서드는 사용자가 이 문제를 해결하도록 도와줍니다. 이 메서드는 HTML DOM 요소를 사용하여 'Google 제공' 브랜드를 이 요소에 첨부합니다. 또는 'Google 제공' HTML DOM 요소를 반환하여 직접 첨부할 수 있게 합니다. 

    다음 코드조각은 이 기능의 사용을 보여줍니다.  

    // attach "powered by Google" branding
google.search.Search.getBranding(document.getElementById("branding"));
...
<div id="branding">Loading...</div>
        
    다음 샘플은 이 개체의 사용을 보여줍니다. 예제 보기(branding.html) 

    추가 샘플

    추가 사용 샘플은 이러한 개념 중 많은 것을 보여주지만 큰 응용프로그램 조각에 포함되어 있습니다. 

    API 개요

    Google AJAX 검색 API는 몇 가지 개체 클래스로 구성됩니다. 
    • google.search.SearchControl - 이 클래스는 많은 searcher 개체에서 사용자 인터페이스와 조정을 제공하며, 각 searcher 개체는 검색을 수행하고 검색결과의 특정 클래스(웹 검색, 지역 검색 등)를 반환하도록 구성됩니다. 
    • google.search.Search - 이 기본 클래스는 모든 'searcher'가 상속하는 클래스입니다. 이 클래스는 모든 searcher 서비스에서 구현해야 하는 인터페이스를 정의합니다. 
    • GResult - 이 기본 클래스는 searcher개체에서 생성한 검색결과를 포함합니다. 
    • google.search.SearcherOptions - 이 클래스를 검색 컨트롤에 추가하면 searcher 개체의 동작을 구성합니다. 
    이러한 클래스의 예상 사용 패턴은 다음과 같습니다.  
    // create a searcher object
var sc = new google.search.SearchControl();

// add one or more searchers, specifying options as needed
var options = new google.search.SearcherOptions();
options.setExpandMode(google.search.SearchControl.EXPAND_MODE_OPEN);
sc.addSearcher(new google.search.WebSearch(), options);
...

// activate the search control by calling it's .draw() method
sc.draw(document.getElementById("myDiv"));
    이러한 기본 단계를 따라 수행하면 검색 컨트롤이 활성 상태가 됩니다. 검색 컨트롤이 표시되면 searcher를 추가할 수 없고 searcher 옵션을 수정할 수 없습니다. 검색 컨트롤의 동작을 변경해야 하는 경우에는 새 검색 컨트롤을 구성하고 활성화해야 합니다. 

    자세한 내용은 검색 API 클래스 참조를 참조하세요. 

    검색결과 스타일 지정New!

    각 검색결과에는 CSS 스타일로 작성한 기본 .html 속성이 포함되어 있습니다. 따라서 의미 있는 각각의 정보가 적절한 클래스 마커 세트와 함께 HTML 마크업에 포함됩니다. 이렇게 하여 개발자의 필요에 맞게 HTML의 스타일을 지정하는 맞춤형 CSS 규칙과 함께 이 HTML을 사용할 수 있습니다. 

    다음에 나오는 섹션에 알 수 있듯이 각 검색결과는 결과 유형별 클래스(예: gs-webResult, gs-localResult)와 gs-result의 일반 검색결과 클래스로 표시된 div 요소에 포함됩니다. 이 구조를 통해 모든 결과에 적용되는 일반 CSS 규칙뿐만 아니라 유형별 규칙을 쉽게 정의할 수 있습니다. 

    이 구조 외에도 google.search.SearchControl로 검색결과를 관리하면 각 검색결과가 검색결과 유형별 클래스(예: gsc-webResult, gsc-localResult)와 gsc-result의 일반 검색 컨트롤 결과 클래스로 표시된 div 요소에 포함됩니다. 각 검색결과 섹션은 검색결과 유형별 클래스(예: gsc-webResult, gsc-localResult)뿐만 아니라 gsc-results의 일반 검색 컨트롤 결과 클래스로 표시된 div 요소에 포함됩니다. 

    이 구조의 결과는 다음과 같습니다.  

    <!-- A collection of web search results in the search control -->
<div class="gsc-results gsc-webResult">

  <!-- A single web result in the search control -->
  <div class="gsc-result gsc-webResult">

    <!-- A single web result, full structure defined below -->
    <div class="gs-result gs-webResult"></div>
  </div>
  ...
</div>

<!-- Similar pattern for local, blog, etc. -->
<div class="gsc-results gsc-localResult"></div>
<div class="gsc-results gsc-blogResult"></div>
  
    각 검색결과의 CSS 구조에 대한 자세한 내용은 다음 섹션을 참조하세요. 

    Flash 및 비 자바스크립트 환경New!

    Flash 개발자와 다른 비 자바스크립트 환경에서 AJAX 검색 API에 액세스해야 하는 개발자를 위해 API는 간단한 RESTful 인터페이스를 표시합니다. 어느 경우든지 지원되는 메서드는 GET이며 응답 형식은 상태 코드가 포함된 JSON 인코딩 결과 집합입니다. 이 인터페이스를 사용하는 응용프로그램은 기존의 모든 이용약관을 따라야 합니다. 특히 주의해야 하는 부분은 요청에서 요청자를 올바르게 확인하는 것과 관련된 영역입니다. 응용프로그램은 항상 유효하고 정확한 http 참조 헤더를 요청에 포함해야 합니다. 또한, 필수는 아니지만 각 요청에 유효한 API 키를 포함하는 것이 좋습니다. 키를 제공하면 문제를 수정하기 위해 사용자에게 연락해야 할 때 사용자 에서 유용한 보조 식별 방법을 제공하게 됩니다. 

    이 인터페이스에 대해 학습을 시작하는 가장 쉬운 방법은 다음을 시도하는 것입니다... 명령줄 도구 curl 또는 wget을 사용하면 다음 명령이 실행됩니다.  

    curl -e http://www.my-ajax-site.com \
        'http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Paris%20Hilton'
    이 명령은 Paris Hilton(q=Paris%20Hilton)에 대한 웹 검색(/ajax/services/search/web)을 수행합니다. 응답은 text/javascript; charset=utf-8의 Content-Type입니다. 아래 응답에서 responseData가 기본 검색 개체 도움말에서 설명한 results 및 cursor 속성과 동일한 것을 볼 수 있습니다.  
    {"responseData": {
 "results": [
  {
   "GsearchResultClass": "GwebSearch",
   "unescapedUrl": "http://en.wikipedia.org/wiki/Paris_Hilton",
   "url": "http://en.wikipedia.org/wiki/Paris_Hilton",
   "visibleUrl": "en.wikipedia.org",
   "cacheUrl": "http://www.google.com/search?q\u003dcache:TwrPfhd22hYJ:en.wikipedia.org",
   "title": "\u003cb\u003eParis Hilton\u003c/b\u003e - Wikipedia, the free encyclopedia",
   "titleNoFormatting": "Paris Hilton - Wikipedia, the free encyclopedia",
   "content": "\[1\] In 2006, she released her debut album..."
  },
  {
   "GsearchResultClass": "GwebSearch",
   "unescapedUrl": "http://www.imdb.com/name/nm0385296/",
   "url": "http://www.imdb.com/name/nm0385296/",
   "visibleUrl": "www.imdb.com",
   "cacheUrl": "http://www.google.com/search?q\u003dcache:1i34KkqnsooJ:www.imdb.com",
   "title": "\u003cb\u003eParis Hilton\u003c/b\u003e",
   "titleNoFormatting": "Paris Hilton",
   "content": "Self: Zoolander. Socialite \u003cb\u003eParis Hilton\u003c/b\u003e..."
  },
  ...
 ],
 "cursor": {
  "pages": [
   { "start": "0", "label": 1 },
   { "start": "4", "label": 2 },
   { "start": "8", "label": 3 },
   { "start": "12","label": 4 }
  ],
  "estimatedResultCount": "59600000",
  "currentPageIndex": 0,
  "moreResultsUrl": "http://www.google.com/search?oe\u003dutf8\u0026ie\u003dutf8..."
 }
}
, "responseDetails": null, "responseStatus": 200}
    프로토콜은 이러한 응답 형식 외에도 callback 인수를 지정하여 트리거되는 클래식 JSON-P 스타일 콜백을 지원합니다. 이 인수가 제공되면 json 개체는 지정된 콜백에 대한 인수로서 전달됩니다.  
    curl -e http://www.my-ajax-site.com \
 'http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Paris%20Hilton&callback=processResults'
    이 명령은 이전 검색과 동일한 웹 검색을 수행하지만 callback을 전달하도록 변경되었습니다. 이 인수를 사용하는 경우 JSON 개체가 반환되지 않고 자바스크립트 호출이 응답으로 반환되며 JSON 개체가 results 매개변수를 통해 전달됩니다.  
    processResults({"responseData": {
 "results": [
  {
   "GsearchResultClass": "GwebSearch",
   "unescapedUrl": "http://en.wikipedia.org/wiki/Paris_Hilton",
   "url": "http://en.wikipedia.org/wiki/Paris_Hilton",
   "visibleUrl": "en.wikipedia.org",
   "cacheUrl": "http://www.google.com/search?q\u003dcache:TwrPfhd22hYJ:en.wikipedia.org",
   "title": "\u003cb\u003eParis Hilton\u003c/b\u003e - Wikipedia, the free encyclopedia",
   "titleNoFormatting": "Paris Hilton - Wikipedia, the free encyclopedia",
   "content": "\[1\] In 2006, she released her debut album..."
  },
  {
   "GsearchResultClass": "GwebSearch",
   "unescapedUrl": "http://www.imdb.com/name/nm0385296/",
   "url": "http://www.imdb.com/name/nm0385296/",
   "visibleUrl": "www.imdb.com",
   "cacheUrl": "http://www.google.com/search?q\u003dcache:1i34KkqnsooJ:www.imdb.com",
   "title": "\u003cb\u003eParis Hilton\u003c/b\u003e",
   "titleNoFormatting": "Paris Hilton",
   "content": "Self: Zoolander. Socialite \u003cb\u003eParis Hilton\u003c/b\u003e..."
  },
  ...
 ],
 "cursor": {
  "pages": [
   { "start": "0", "label": 1 },
   { "start": "4", "label": 2 },
   { "start": "8", "label": 3 },
   { "start": "12","label": 4 }
  ],
  "estimatedResultCount": "59600000",
  "currentPageIndex": 0,
  "moreResultsUrl": "http://www.google.com/search?oe\u003dutf8\u0026ie\u003dutf8..."
 }
}
, "responseDetails": null, "responseStatus": 200})
    마지막으로 이 프로토콜은 callback 및 context 인수를 지원합니다. 이러한 url 인수를 지정하면 결과는 callback(context, results, status, details, unused)의 서명과 함께 직접 자바스크립트 호출로 인코딩됩니다. 다음 명령과 응답에 나타나는 미묘한 차이점을 확인하세요.  
    curl -e http://www.my-ajax-site.com \
 'http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Paris%20Hilton&callback=foo&context=bar'
    이 명령은 이전 검색과 동일한 웹 검색을 수행하지만 callback 및 context를 전달하도록 변경되었습니다. 이러한 인수를 사용하는 경우 JSON 개체가 반환되지 않고 자바스크립트 호출이 반환되며 JSON 개체가 results 매개변수를 통해 전달됩니다.  
    foo('bar',{
 "results": [
  {
   "GsearchResultClass": "GwebSearch",
   "unescapedUrl": "http://en.wikipedia.org/wiki/Paris_Hilton",
   "url": "http://en.wikipedia.org/wiki/Paris_Hilton",
   "visibleUrl": "en.wikipedia.org",
   "cacheUrl": "http://www.google.com/search?q\u003dcache:TwrPfhd22hYJ:en.wikipedia.org",
   "title": "\u003cb\u003eParis Hilton\u003c/b\u003e - Wikipedia, the free encyclopedia",
   "titleNoFormatting": "Paris Hilton - Wikipedia, the free encyclopedia",
   "content": "In 2006, she released her debut album \u003cb\u003eParis\u003c/b\u003e..."
  },
  {
   "GsearchResultClass": "GwebSearch",
   "unescapedUrl": "http://www.imdb.com/name/nm0385296/",
   "url": "http://www.imdb.com/name/nm0385296/",
   "visibleUrl": "www.imdb.com",
   "cacheUrl": "http://www.google.com/search?q\u003dcache:1i34KkqnsooJ:www.imdb.com",
   "title": "\u003cb\u003eParis Hilton\u003c/b\u003e",
   "titleNoFormatting": "Paris Hilton",
   "content": "Self: Zoolander. Socialite \u003cb\u003eParis Hilton\u003c/b\u003e was..."
  },
  ...
 ],
 "cursor": {
  "pages": [
   { "start": "0", "label": 1 },
   { "start": "4", "label": 2 },
   { "start": "8", "label": 3 },
   { "start": "12","label": 4 }
  ],
  "estimatedResultCount": "59600000",
  "currentPageIndex": 0,
  "moreResultsUrl": "http://www.google.com/search?oe\u003dutf8..."
 }
}
, 200, null)

    코드조각 New! 

    다음 섹션에서는 Flash, Java 및 php에서 API 액세스를 보여주는 코드조각을 보여줍니다. JSON 응답을 처리하는 데 문제가 있을 경우에는 JSON.org 사이트를 방문하여 다양한 JSON 라이브러리를 참조하는 페이지의 중간 이후 내용을 확인해 보세요. 이전 섹션에서 설명한 여러 가지 Google API 서비스를 REST API를 통해 사용하는 방법에 대해서는 이 기준 URL에 대한 테이블 매핑 메서드를 참조하세요. 

    Flash 액세스

    다음 코드조각은 Flash에서 AJAX 검색 API를 요청하는 방법을 보여줍니다. ActionScript 3.0(AS3) 핵심 라이브러리의 JSON을 사용하세요.  
    var service:HTTPService = new HTTPService();
service.url = 'http://ajax.googleapis.com/ajax/services/search/web';
service.request.v = '1.0';
service.request.q = 'Paris Hilton';
service.resultFormat = 'text';
service.addEventListener(ResultEvent.RESULT, onServerResponse);
service.send();

private function onServerResponse(event:ResultEvent):void {
  try {
    var json:Object = JSON.decode(event.result as String);
    // now have some fun with the results...
  } catch(ignored:Error) {
  }
}

    Java 액세스

    다음 코드조각은 Java에서 AJAX 검색 API를 요청하는 방법을 보여줍니다. http://www.json.org/java/에서 json 라이브러리 사용을 확인하세요.  
    URL url = new URL("http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Paris%20Hilton");
URLConnection connection = url.openConnection();
connection.addRequestProperty("Referer", "http://www.mysite.com/index.html");

String line;
StringBuilder builder = new StringBuilder();
BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream()));
while((line = reader.readLine()) != null) {
 builder.append(line);
}

JSONObject json = new JSONObject(builder.toString());
// now have some fun with the results...

    Php 액세스

    다음 코드조각은 php에서 AJAX 검색 API를 요청하는 방법을 보여줍니다. 이 샘플에서는 PHP 5.2를 가정합니다. 기존 PHP 설치에 대해서는 이 댓글을 참조하세요.  
    $url = "http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Paris%20Hilton"

// sendRequest
// note how referer is set manually
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_REFERER, "http://www.mysite.com/index.html");
$body = curl_exec($ch);
curl_close($ch);

// now, process the JSON string
$json = json_decode($body);
// now have some fun with the results...
    이 인터페이스에 대한 전체 도움말은 클래스 참조 설명서를 참조하세요. 

    문제해결

    코드에 문제가 발생하는 경우 다음을 수행하세요. 
    • API 키가 올바른지 확인합니다. 
    • 철자가 올바른지 확인합니다. 자바스크립트는 대소문자를 구분하는 언어임을 기억하세요. 
    • 자바스크립트 디버거를 사용합니다. Firefox에서 자바스크립트 콘솔 또는 Firebug를 사용할 수 있습니다. Internet Explorer에서는 Microsoft 스크립트 디버거를 사용할 수 있습니다. 

      • AJAX 검색 API 토론 그룹을 검색합니다. 질문에 답변이 되는 게시물을 찾을 수 없는 경우 문제를 보여주는 웹페이지에 대한 링크를 포함하여 질문을 그룹에 게시하십시오.