応援口コミAPI


URL:http://api.gnavi.co.jp/PhotoSearchAPI/20150630/

※旧バージョン(http://api.gnavi.co.jp/ouen/ver1/PhotoSearch/)をお使いの場合は、こちらのバージョンに変更をお願いします。
詳細は、「APIのURL変更のお知らせ」をご確認ください。

リクエストパラメータ

※リクエストパラメータがkeyidのみの場合は、パラメータ不足のため、エラーとして値が返ります。

パラメータ名 必須 説明 備考
keyid String アクセスキー ぐるなびより提供されたアクセスキー
format   String レスポンス形式 xmlまたはjson(callback関数指定時にJSONP形式で出力
callback   String コールバック関数 formatが「json」の場合のみ
shop_id   String 店舗ID 「,」区切りで店舗IDを複数検索可能(10個まで)
latitude △※1 number 緯度 分秒十進式
世界測地系で指定
longitude △※1 number 経度 分秒十進式
世界測地系で指定
range ※2 integer 範囲 GPS検索対象半径を設定する。単位はm。
緯度/経度からの検索範囲(半径)
1:300m、2:500m、3:1000m、
4:2000m、5:3000m
shop_name   String 店舗名 UTF-8でエンコードすること
area   String 場所(フリーワード) UTF-8でエンコードすること
comment   String コメント UTF-8でエンコードすること
first_shop_message   String 店舗からの最初のメッセージ UTF-8でエンコードすること
menu_name   integer メニュー名 UTF-8でエンコードすること
photo_scene_id   integer シーン 「,」区切りでシーンIDを9個まで指定可能
1:友人・同僚と,2:宴会,3:パーティー,4:女子会,5:デート,6:誕生日・記念日,7:お一人様,8:ママ会,9:その他
hit_per_page   integer ヒット件数 1回のリクエストで得る最大投稿件数(デフォルト:15、上限:50)
offset_page   integer 検索開始ページ 検索開始ページ位置(デフォルト:1)
offset   integer 検索開始位置 検索開始レコード位置(デフォルト:1)
order ※3 String ソートキー ソートキー(デフォルト:vote_date)
vote_date:投稿日時(緯度、経度を設定した場合、昇順のみ有効)
distance:現在地からの距離(緯度、経度を設定した場合のみ有効)
sort ※3 integer ソート順 ソート順
0:昇順
1:降順(デフォルト:昇順)
vote_date   integer 投稿日で絞込み 現在日より過去何日間の投稿を抽出対象とするかを設定
photo_genre_id   integer 写真ジャンルで絞込み 「,」区切りで3個まで写真ジャンルIDを指定可能
1:料理・ドリンク,2:店内・外観,3:人物・その他

レスポンス

パラメータ名 出現回数 説明 備考
Response 1 ComplexType レスポンスルート  
@api_version - string APIのバージョン  
  total_hit_count 1 integer 該当件数  
  hit_per_page 1 integer 表示件数  
  photo 複数回 ComplexType 応援口コミ情報  
   vote_id   1 integer 投稿ID  
   photo_genre_id   1 integer 写真ジャンルID  
   photo_genre_name  1 string 写真ジャンル名称  
   photo_scene_id  1 integer シーンID  
   photo_scene_name  1 string シーン名称  
   nickname   1 string ニックネーム  
   shop_id   1 string 店舗ID  
   shop_name   1 string 店舗名称  
   shop_url   1 string PCサイトURL  
   prefname   1 string 都道府県  
   menu_id   1 integer メニューID  
   menu_name   1 string メニュー名  
   menu_finish_flag  1 integer メニュー終了フラグ 当該のメニューが終了しているかを示す
0:提供中、1:終了
   areaname_l   1 string 大エリア名  
   areaname_m   1 string 中エリア名  
   areaname_s   1 string 小エリア名  
   image_url   1 ComplexType    
    url_1024  1 stirng 画像URL(1024px)  
    url_320  1 stirng 画像URL(320px)  
    url_250  1 stirng 画像URL(250px)  
    url_200  1 stirng 画像URL(200px)  
   comment   1 string コメント  
   total_score   1 number 総合評価  
   category   1 string 11文字業態  
   distance   1 integer 距離 緯度、経度が設定されている場合のみ返却される
単位はメートル
   latitude   1 string 緯度  
   longitude   1 string 経度  
   umaso_count   1 integer うまそ数  
   update_date   1 timestamp 投稿日時  
   messages   1 ComplexType    
    user_message_count 1 integer メッセージ返信件数(ユーザー)  
    shop_messege_count 1 integer メッセージ返信件数(店舗)  
    first_shop_message 1 ComplexType 店舗からの最初のメッセージ  
     message_body 1 string メッセージ本文  
  send_date 1 string メッセージ送信日時  

※1店舗IDまたは検索ワードが設定されている場合は無視される。どちらか一方しか設定されない場合はエラー返却。設定された地点から近い順にソートされる。
※2店舗IDまたは検索ワードが設定されている場合は無視される。緯度、経度を設定した場合のみ有効。
※3緯度、経度が設定されている場合は無視される。

サンプル

下記よりご確認ください。またAPIテストツールもご用意しています。

<!DOCTYPE html>
<html lang="ja" dir="ltr">
<head>
<meta charset="utf-8" />
<title>JSONPで応援口コミAPIの結果を取得するサンプルコード</title>
</head>
<body>
<input type="text" placeholder="enter your access key here" class="js--key"><input type="button" value="apply" class="js--apply" />
<script src="https://code.jquery.com/jquery-1.11.2.min.js"></script>
<script>

(function(){

  var url = 'http://api.gnavi.co.jp/PhotoSearchAPI/20150630/?callback=?';
  var params = {
    menu_name: 'ハンバーグ',
    keyid: '',
    format: 'json'
  };

  var showResult = function(result){
    var res = '';
    if ( result.response.total_hit_count > 0 ) {
      var res = "";
      for ( var i in result.response){
        var r = result.response[i];
        r = r.photo;
        if(typeof r != 'undefined') {
          if(typeof r.shop_name != undefined) res += r.shop_name + ':' + r.comment + '\n \n';
        }
      }
    } else {
      var res = '検索結果が見つかりませんでした。';
    }
    alert(res);
  }

  $(document).on('click', '.js--apply', function(){
    params.keyid = $('.js--key').val();
    $.getJSON(url, params, function(result){
      showResult(result);
    });
  });

})(jQuery);

</script>
</body>
</html>
                
<?php
/*****************************************************************************************
  ぐるなびWebサービスの応援口コミAPIを実行しハンバーグの口コミを取得しパースするプログラム
  注意:アクセスキーはユーザ登録後に発行されるキーを指定してください。
*****************************************************************************************/

//エンドポイントのURIとフォーマットパラメータを変数に入れる
$uri   = "http://api.gnavi.co.jp/PhotoSearchAPI/20150630/";
//APIアクセスキーを変数に入れる
$acckey= "input your accesskey";
//返却値のフォーマットを変数に入れる
$format= "json";
//メニュー名をURLエンコーディング
$menu_name = urlencode("ハンバーグ");
//ページごとのヒット件数を入れる変数を初期化
$hit_per_page = 0;

//URI組み立て
$url  = sprintf("%s%s%s%s%s%s%s", $uri, "?format=", $format, "&keyid=", $acckey, "&menu_name=",$menu_name);
//API実行
$json = file_get_contents($url);
//取得した結果をオブジェクト化
$obj  = json_decode($json);
$data = $obj->{"response"};

//結果をパース
//トータルヒット件数、店舗番号、店舗名、メニュー名、コメントを出力
foreach((array)$data as $key => $val){
   if(strcmp($key, "total_hit_count" ) == 0 ){
       echo "total:".$val."\n";
   }
   if(strcmp($key, "hit_per_page" ) == 0 ){
       $hit_per_page = $val;
   }

   for($i = 0; $i < $hit_per_page ; $i++){
       if(strcmp($key, $i) == 0){
            $restArray = $val->{'photo'};
            if(checkString($restArray->{'shop_id'}))   echo $restArray->{'shop_id'}."\t";
            if(checkString($restArray->{'shop_name'})) echo (string)$restArray->{'shop_name'}."\t";
            if(checkString($restArray->{'menu_name'})) echo (string)$restArray->{'menu_name'}."\t";
            if(checkString($restArray->{'comment'}))    echo (string)$restArray->{'comment'}."\n";


       }
    }
}

#文字列であるかをチェック
function checkString($input)
{

    if(isset($input) && is_string($input)) {
        return true;
    }else{
        return false;
    }

}
?>
                
#!/usr/bin/env python
# -*- coding: utf-8 -*-
#*****************************************************************************************
# ぐるなびWebサービスの応援口コミAPIを実行しハンバーグの口コミを取得しパースするプログラム
# 注意:アクセスキーはユーザ登録後に発行されるキーを指定してください。
#*****************************************************************************************
import sys
import urllib
import json

####
# 変数の型が文字列かどうかチェック
####
def is_str( data = None ) :
  if isinstance( data, str ) or isinstance( data, unicode ) :
    return True
  else :
    return False

####
# 初期値設定
####
# APIアクセスキー
keyid     = "input your accesskey"
# エンドポイントURL
url       = "http://api.gnavi.co.jp/PhotoSearchAPI/20150630/"
# メニュー
menu_name = u"ハンバーグ"
#文字コード
encoding = 'utf-8'

####
# APIアクセス
####
# URLに続けて入れるパラメータを組立
query = [
  ( "format",    "json"    ),
  ( "keyid",     keyid     ),
  ( "menu_name", menu_name.encode(encoding) )
]
# URL生成
url += "?{0}".format( urllib.urlencode( query ) )
# API実行
try :
  result = urllib.urlopen( url ).read()
except ValueError :
  print u"APIアクセスに失敗しました。"
  sys.exit()

####
# 取得した結果を解析
####
data = json.loads( result )

# エラーの場合
if "error" in data :
  if "message" in data :
    print u"{0}".format( data["message"] )
  else :
    print u"データ取得に失敗しました。"
  sys.exit()

# ヒット件数取得
total_hit_count = None
if "total_hit_count" in data["response"] :
  total_hit_count = data["response"]["total_hit_count"]

#ページごとの件数を取得
hit_per_page = None
if "hit_per_page" in data["response"] :
  hit_per_page = data["response"]["hit_per_page"]

# ヒット件数が0以下、または、ヒット件数がなかったら終了
if total_hit_count is None or total_hit_count <= 0 or hit_per_page is None or hit_per_page <= 0 :
  print u"指定した内容ではヒットしませんでした。"
  sys.exit()

# ヒット件数表示
print "{0}件ヒットしました。".format( total_hit_count )
print "----"

# 出力件数
disp_count = 0

# 応援口コミデータ取得
for i in range( hit_per_page ) :
  photo = data["response"]["{0}".format(i)]["photo"]
  line                 = []
  id                   = ""
  name                 = ""
  mname                = ""
  comment              = ""

  # 店舗番号
  if "shop_id" in photo and is_str( photo["shop_id"] ) :
    id = photo["shop_id"]
  line.append( id )

  # 店舗名
  if "shop_name" in photo and is_str( photo["shop_name"] ) :
    name = photo["shop_name"]
  line.append( name )

  # メニュー名
  if "menu_name" in photo and is_str( photo["menu_name"] ) :
    mname = photo["menu_name"]
  line.append( mname )

  # コメント
  if "comment" in photo and is_str( photo["comment"] ) :
    comment = photo["comment"]
  line.append( comment )

  # タブ区切りで出力
  print "\t".join( line )
  disp_count += 1

# 出力件数を表示して終了
print "----"
print u"{0}件出力しました。".format( disp_count )
sys.exit()
                
package jp.javadrive;
import java.net.URL;
import java.net.HttpURLConnection;
import java.net.URLEncoder;
import java.util.Iterator;
import com.fasterxml.jackson.databind.*;
/*******************************************************************************
 * ぐるなびWebサービスの応援口コミ検索APIでハンバーグの口コミを実行しパースするプログラム
 * 注意:アクセスキーはアカウント登録時に発行されたキーを指定してください。
 *      JsonをパースするためにライブラリにJacksonを追加しています。
 ******************************************************************************/
public class TestJavaOuen {

  public static void main(String[] args) {
            //アクセスキー
      String acckey = "input your accesskey";
      //返却形式
      String format = "json";
      //メニュー名のハンバーグをURLエンコーディング
      String menu = getEnc("ハンバーグ");
      //エンドポイント
      String gnaviRestUri = "http://api.gnavi.co.jp/PhotoSearchAPI/20150630/";
      String prmFormat = "?format=" + format;
      String prmKeyid = "&keyid=" + acckey;
      String prmMenu = "&menu_name=" + menu;
      //URI組み立て
      StringBuffer uri = new StringBuffer();
      uri.append(gnaviRestUri);
      uri.append(prmFormat);
      uri.append(prmKeyid);
      uri.append(prmMenu);

      //APIを実行し結果を出力
      getNodeList(uri.toString());
  }

  private static void getNodeList(String url) {

      try {
          URL restSearch = new URL(url);
          HttpURLConnection http = (HttpURLConnection)restSearch.openConnection();
          http.setRequestMethod("GET");
          http.connect();
          //Jackson
          ObjectMapper mapper = new ObjectMapper();
          viewJsonNode(mapper.readTree(http.getInputStream()));

      } catch (Exception e) {
          //TODO: 例外は考慮していません
      }
  }

  private static void viewJsonNode(JsonNode rootList){
        if(rootList != null){
          JsonNode nodeList = rootList.path("response");
          //トータルヒット件数
          String hitcount   = "total:" + nodeList.path("total_hit_count").asText();
                System.out.println(hitcount);
          //photoのみ取得
        Iterator<JsonNode> photo = nodeList.iterator();
        // 店舗ID、店舗名、メニュー名、コメントを表示
        while(photo.hasNext()){
              JsonNode i = photo.next();
            JsonNode p = i.get("photo");
              if(p != null){
              String id = p.path("shop_id").asText();
                    String name = p.path("shop_name").asText();
                    String menu_name = p.path("menu_name").asText();
              String comment = p.path("comment").asText();

              System.out.println(id + "¥t" + name + "¥t" + menu_name + "¥t" + comment);
              }
          }
        }
  }

  private static String getEnc(String str){
      String encStr = "";
      try {
        encStr = URLEncoder.encode(str,"UTF-8");
      }catch(Exception e) {
          //TODO:例外を考慮していません
      }
      return encStr;
  }
}
                

エラー仕様

パラメータ名
(タグ名)
出現回数 説明
gnavi 1 complexType ルートノード
@api_version - string APIのバージョン
  error 複数回 complexType エラー
  code 1 integer エラーコード(詳細は「エラーコード一覧」をご覧ください)
message 1 string エラーメッセージ

エラーコード一覧

エラーコード エラーメッセージ エラー内容
429 Too Many Access リクエスト回数上限超過
600 NoShop 指定された店舗の情報が存在しない。
601 Invalid Access 不正なアクセス(認証エラー)。
602 Invalid Shop Number 不正なぐるなび店舗IDパラメータが指定された。
603 InvalidType 不正なパラメータが指定された。
604 Internal Server Error 処理中にエラーが発生した。

サンプルエラーレスポンス

<gnavi api_version="20150630">
  <error>
    <code>603</code>
    <message>指定されたパラメーターは存在しません</message>
  </error>
</gnavi>
              

データを正しく返却できない際は、上記のようなエラーデータを返却します(返却形式がXMLの場合)。

さっそく「ぐるなび API」を使ってみる