「SEOmoz-API」のリクエスト・レスポンスフォーマット

Yahoo!SiteExplorer亡き後の競合調査ツールとして有力な“SEOmoz”。

そのAPIにおけるリクエストとレスポンスフォーマットについて、本家のWikiの記事を私家版翻訳しました。
とは言っても、いろいろなところ寄り道していますが… 

SEOmozって何？という方はまずは以下の記事をご覧下さい。

1. SEOmoz linkscape API解説～はじめに～
2. 「SEOmozまとめ」SEOmozAPIを使うとできること(1)

 

元記事はこちらです。「The SEOmoz API / Request-Response Format」

リクエストフォーマット

FreeAPI・SiteIntelligenceAPI関わらず、全てのAPIは、コール先とそのパラメータで動き決めます。

データを得るためには、GETかPOSTでSEOmozのAPIにリクエストを送る必要があります。

正しいリクエストの書式

リクエストは以下の書式です。

http://lsapi.seomoz.com/resource/api_call/argument?query_string=values

• http://lsapi.seomoz.com/：APIのホストネームの部分で、ここはいつも同じです。
• resource/ ： ここもいつも変わりません（今は）
• api_call/　：　
  どのAPIを呼び出すかによって変わる部分です。具体的には以下です。
  URL Metrics API　→　”url-metrics”
  Links API　→　”links”
  Top Pages API → “top-page”
  Anchor Text API → “anchor-text”
• query_string=values　：　それぞれのAPI-CALLごとにある呼び出しパラメータの部分です。

例えば

http://lsapi.seomoz.com/linkscape/url-metrics/query_string=values&query_string=values…

となります。

 

認証を付与する

ここにさらに、認証情報を加えます。

認証の仕方には2種類あって、

1. いわゆるBasic認証
2. リクエストの中に認証キーを入れる「Signed認証」

のどちらかです。基本どちらでも構いません。

Basic認証を使う場合は、書式として

http://ACCESS_ID:[email protected]/linkscape/url-metrics/seomoz.org

としてリクエストをすることになります。

Signed認証の場合は多少複雑で

AccessID=NKzHzYz2BI4SXf&Expires=1225138899&Signature=LmXYcPqc%2BkapNKzHzYz2BI4SXfC%3D

といったものをクエリの最後につけます。

この中にあるAccessIDは、1アカウントに1つ与えられる、アカウント識別のための固有IDです。SEOmozのメンバー登録をした後に分かるようになります。（→ 実際に今すぐ発行する場合はこちらへ）

Expiresはこのリクエストがいつまで効力を持つかという値です。セッションのような感覚で使われることが多いようで、コードとしては

$expire = time( void ) + 600 ;

のように、現在時間から毎回算出してしまうことが多いようです。

最後のSignatureは、AccessIDをHMAC-SHA1でハッシュ化した物です。

SHA-1 とは“Secure Hash Algorithm”のことで、米国政府標準の暗号ハッシュアルゴリズムキーとのことです。（参照：HMACSHA1 クラス (System.Security.Cryptography)）

キーとしては、AccessIDと一緒に手に入るSecretKeyを使うことになります。

そしてそれを用いて、例えば

if(!empty($smoz_req_url) ) {
$objectURL = $smoz_req_url ;
$service = ‘http://lsapi.seomoz.com/linkscape/url-metrics/’ ;
$accessid = ‘【あなたのID】’ ;
$secretKey = “【あなたのキー】” ;
$expire = time( void ) + 600 ;
$stringToSign = $accessid.”n”.$expire;
$binarySignature = hash_hmac(‘sha1’, $stringToSign, $secretKey, true);
$urlSafeSignature = urlencode(base64_encode($binarySignature));

のようにして、クエリを作り上げます。

 

個々のコールごとのパラメータ

これについては、ひとまずこちらのページの中断表組みの辺りをご覧頂くのが速いかと…

http://apiwiki.seomoz.org/w/page/13991145/Request-Response%20Format

ちなみに1番右の列の「In Free API？」にYESがはいっている物が、FreeAPIで使える物です。
これを見てると、SiteIntelligenceAPIを使ってみたくなります…恐るべしフリーミアムモデル。

 

レスポンスフォーマット

レスポンスは、GoogleなどのようなXMLではなく、JSON形式で返却されてきます。

例えば

{“feid”:367502, “upl”:”org.seomoz/”, “ur”:””, “utrp”:4.844881298838326, }

のような形です。

キーのアルファベットは、先ほどのページの表の「Response Field」に当たります。

上の物なら

• 「リンクジュースを流してくれるサブドメインの外部リンクが、367502本」
• 「ルートドメインは”org.seomoz”」
• 「canonical属性は設定されていない」
• 「mozTrustランクは4.8くらい」

という結果が返ってきています。

後はこれを

$smoz_url = rawurlencode($smoz_url) ;
$smoz_json = file_get_contents(build_query($smoz_url));
$smoz_data = json_decode($smoz_json);

といった形で、GET後にJSON形式から配列に変換してしまうのが楽ではないかなと思います。

このような形でSEOmozとデータの受け渡しを行います。

参考・参照ページ

• Generating-a-Valid-Request
• Available-API-Calls
• HttpBasicAuth
• json_decode：：PHP Manual