Feature request occurrence API: explain facetLimit in documentation and include paging details (facetOffset, facetLimit, count etc) in response

[nickynicolson]

The facet parameters for the occurrence API include facetOffset and facetLimit and the documentation states that these are to allow paging requests through large number numbers of facet values.

The limit and offset values for result paging are documented with maximum values (https://techdocs.gbif.org/en/openapi/v1/occurrence#/Searching%20occurrences/searchOccurrence), and the JSON response includes a result count to enable the user to determine how many paging calls are required.

Please can this be similarly implemented for facets? I think the response could look something like this - where offset, limit, endOfRecords and count are specified within the facet element. (But maybe endOfRecords would be better named endOfFacets?)

{
  "offset": 0,
  "limit": 0,
  "endOfRecords": false,
  "count": 3513561,
  "results": [
    
  ],
  "facets": [
    {
      "field": "RECORDED_BY",
      "offset": 0,
      "limit": 5,
      "endOfRecords": false,
      "count": nnnnn,
      "counts": [
        {
          "name": "hubbard, c.e.",
          "count": 9713
        },
        {
          "name": "spruce, r.",
          "count": 9375
        },
        {
          "name": "richards, h.m. (mrs)",
          "count": 7530
        },
        {
          "name": "burchell",
          "count": 7498
        },
        {
          "name": "henry, a.",
          "count": 7422
        }
      ]
    }
  ]
}