TotalResults count doesn't match with the actual results returned in YouTube v3 search API

Question

We are using youtube v3 search API. We are getting mismatch in the "totalResults" count and the list of items returned in the response.items field. I am requesting 50 videos in the request. Response returned shows totalResults count as 65 but the response payload has only 3 videos.

API : www.googleapis.com/youtube/v3/search/list

Request Payload

{key=API_KEY, maxResults=50, order=date, part=snippet, publishedAfter=2017-03-20T23:59:59.999-04:00, publishedBefore=2017-04-19T23:59:59.001-04:00, q=( ( "Wood Mackenzie" OR "Wood Mac" OR Woodmac OR @woodmackenzie ) AND NOT (fleetwood OR "fleet wood" OR 9WoodMac ) )  , type=video}

Response Payload

{
 "kind": "youtube#searchListResponse",
 "etag": "\"m2yskBQFythfE4irbTIeOgYYfBU/HTW4WQODZeERIv51VrRfOhir8dg\"",
 "nextPageToken": "CDIQAA",
 "regionCode": "US",
 "pageInfo": {
  "totalResults": 65,
  "resultsPerPage": 50
 },
 "items": [
  {
   "kind": "youtube#searchResult",
   "etag": "\"m2yskBQFythfE4irbTIeOgYYfBU/lnNNrToZHGTehIEJ6bvEx5RZMo4\"",
   "id": {
    "kind": "youtube#video",
    "videoId": "obzlB21t904"
   },
   "snippet": {
    "publishedAt": "2017-04-14T11:38:08.000Z",
    "channelId": "UC60Sa1LQjgy_a-K8ThN4eQw",
    "title": "Fleet wood mac Live at Leeds",
    "description": "",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/obzlB21t904/default.jpg",
      "width": 120,
      "height": 90
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/obzlB21t904/mqdefault.jpg",
      "width": 320,
      "height": 180
     },
     "high": {
      "url": "https://i.ytimg.com/vi/obzlB21t904/hqdefault.jpg",
      "width": 480,
      "height": 360
     }
    },
    "channelTitle": "KEVIN MARSHALL",
    "liveBroadcastContent": "none"
   }
  },
  {
   "kind": "youtube#searchResult",
   "etag": "\"m2yskBQFythfE4irbTIeOgYYfBU/uYuuTAL3vtnFI1WOYjth0cso2Xo\"",
   "id": {
    "kind": "youtube#video",
    "videoId": "gHAn0SbwKMg"
   },
   "snippet": {
    "publishedAt": "2017-04-06T22:17:31.000Z",
    "channelId": "UC3_MxBSSbmGznoSTgoBQ7_w",
    "title": "Beat Club: British Invasion 60's, Pt-2; Animals-Move-Fleet Wood Mac-J.Mayall-Who-Pacemakers-Kinks",
    "description": "Eric Burdon & Animals: C.C. Rider 0:01 The Move: Wild Tiger Woman 3:55 Fleet Wood Mac: Dragonfly 6:26 John Mayall: My Pretty Girl 9:47 Thunderclap ...",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/gHAn0SbwKMg/default.jpg",
      "width": 120,
      "height": 90
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/gHAn0SbwKMg/mqdefault.jpg",
      "width": 320,
      "height": 180
     },
     "high": {
      "url": "https://i.ytimg.com/vi/gHAn0SbwKMg/hqdefault.jpg",
      "width": 480,
      "height": 360
     }
    },
    "channelTitle": "ROCK&POPS1_koba",
    "liveBroadcastContent": "none"
   }
  },
  {
   "kind": "youtube#searchResult",
   "etag": "\"m2yskBQFythfE4irbTIeOgYYfBU/tapelxOG4Q3gZRJCR2qaVdt-ZO8\"",
   "id": {
    "kind": "youtube#video",
    "videoId": "5GvLbFBdcF4"
   },
   "snippet": {
    "publishedAt": "2017-04-02T04:48:47.000Z",
    "channelId": "UC6fn383TI1HVDYW4dSEIogQ",
    "title": "\"Dreams\" by fleet wood mac (vocal cover)",
    "description": "I do not own this song. I do not make a profit off of this song. It belongs to the person(s) who wrote it. Please subscribe and comment below any suggestions?!",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/5GvLbFBdcF4/default.jpg",
      "width": 120,
      "height": 90
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/5GvLbFBdcF4/mqdefault.jpg",
      "width": 320,
      "height": 180
     },
     "high": {
      "url": "https://i.ytimg.com/vi/5GvLbFBdcF4/hqdefault.jpg",
      "width": 480,
      "height": 360
     }
    },
    "channelTitle": "Musikallitee",
    "liveBroadcastContent": "none"
   }
  }
 ]
}

Answer 1

As described in the documentation itself, the totalResults is:

integer

The total number of results in the result set.Please note that the value is an approximation and may not represent an exact value. In addition, the maximum value is 1,000,000.

You should not use this value to create pagination links. Instead, use the nextPageToken and prevPageToken property values to determine whether to show pagination links.

The value is only an approximation/estimate, but not the exact value for the total number of items returned. I've tested the API with the same details as yours and the value tends to change from 63, to 64, and 65.

With all that said, there is nothing wrong in your code. It's just the expected behavior. Unfortunately, it is not stated anywhere as to where the value of totalResults is based on or where it is best used. It's best to proceed with an implementation that doesn't rely on this parameter.