Zenn
😈

ドキュメントは原語で読もうねって話

2020/12/03に公開
Stack Overflow
YouTube Data API
idea

はじめましてアクマちゃんです😈
今日はzenn.devに登録したのでテストがてら軽い記事を書いてみます。

要約

  • 日本語に翻訳されたドキュメントは不正確なことがあるからできれば原語で読みましょう。

何があったか

一昨日、ワガハイがYouTube Data API v3でいろいろ試していると、レスポンスが思てたんと違いました。

投げたクエリ（改行してます）

https://www.googleapis.com/youtube/v3/search
?part=id
&channelId=UC5fslQUCCo3OE1EaA1n5ZmQ
&key=xxxxxxxxx
&publishedAfter=2019-01-15T08:09:38Z
&publishedBefore=2019-01-15T10:09:38Z
&order=date

2019-01-15T09:09:38Zに投稿された動画が存在したので、その1件だけを取得するために投稿日時を絞ったクエリです。

レスポンス

{
  "kind": "youtube#searchListResponse",
  "etag": "iLvO2LgGDksqADNU-_xPwG4QMCU",
  "nextPageToken": "CAUQAA",
  "regionCode": "JP",
  "pageInfo": {
    "totalResults": 49,
    "resultsPerPage": 5
  },
  "items": [
    {
      "kind": "youtube#searchResult",
      "etag": "Adtll-9lbQDiKGJEkBb2IEjPfjw",
      "id": {
        "kind": "youtube#video",
        "videoId": "d4Z7MZo3-Ac"
      }
    }
  ]
}

期待通りにitemsには1件だけ動画のデータが格納されています。
ただ、pageInfoの中の情報が何かおかしいような・・・？
resultPerPageに関しては取得した件数に関係なく1ページのアイテム数が返ってくるのならこれでも問題ないとは思いますが、totalResultsが49・・・？

公式のドキュメントを見ると以下のように書いてあります。
公式APIドキュメントより抜粋

pageInfo.totalResults integer 結果セット内の結果の総数。

実は49件返ってきているのかと思いpageTokenを使い次のページを取得してみるもデータはなし。
なのでstackoverflowで質問してみました。投稿はこちら

すると次の日に返信してくれている方が。

stackoverflowで頂いた返信

（要約）

なぜpageInfo.totalResultsが1ではなく49なのか？
仕様書に以下のように書いてあります。

結果セット内の結果の総数です。 気をつけてほしいのはこれはだいたいの数値であり正確な数値を表しているとは限りません。さらに、最大の値は1,000,000です。
この値をパジネーションリンクの作成の際に使用しないでください。パジネーションリンクの作成にはprevPageTokenとnextPageTokenを使用してください。

え？😂

書いてなくね？😂

まあタイトルからお察しかと存じ上げますが、原典（英語）の仕様書に書いてある上記の非常に重要な注意書きが日本語ドキュメントではまるまる抜けてしまっているんですね！
しかもこの返信者さんがさらに詳しく調べて情報をくれました。

CMのあと、驚きの結末が！！！

（要約）

他の翻訳されているすべての言語でpageInfo.totalResultsのドキュメントを見てみると面白い事がわかりました。
Google翻訳にかけてみても、英語の仕様に近い形で記述されている言語はひとつもありませんでした。

なんと・・・😩

結論

翻訳されたドキュメントはあくまで翻訳であって正式なドキュメントじゃないということを肝に銘じて、日頃から原語のドキュメントをチェックする習慣をちゃんとつけましょうねって話でした。

...

っていうか適当な数字が返ってくるプロパティって何よGoogleさん・・・

Discussion