Search box for scientific and common name

[MortenHofft]

I removed the various links and one heading and just left the text box because that will be needed to lookup lists of taxa by scientificName and commonName.

_Originally posted by @jloomisVCE in https://github.com/VtEcostudies/VAL_GBIF_Wordpress/issues/1#issuecomment-1238404184_

[MortenHofft]

I would like to understand this part better.

From what I can deduce from the browser traffic it looks like you do a

• call to your own checklist. e.g. puma concolor https://api.gbif.org/v1/species/suggest?q=te&datasetKey=0b1735ff-6a66-454b-8686-cae1cbc732a2&advanced=1
• Then when the user clicks search, you do an additional call to the match API (using whatever is in the search box, which is typically what was in the suggest) and then translate that into either a taxon search if there is a match or a free text search if it is unknown or a common name?

Is that correctly understood?

You still have that option on the homepage, but you would also like to have it on the data explorer? Is that because it limits the options to the checklist?

I'm trying to understand if there is something we implement in the widget to make it more useful.

I do not think having a big hero banner on top with an input field is a natural way to search. I'd much rather that we found a good way to add that as a filter, that behaved as you think it should.

Can you explain a bit more about what it is you are trying to achieve with that banner with the input/filter?

[jloomisVCE]

Thanks. I might be missing something about this UI and I'm probably stuck on how we've approached this in the past. We are trying to accomplish a few things:

• Ability to see separated lists of species on the map. For example, if I enter 'Sterna', I might want to see all records for that GENUS together, but that's rare. Users are more likely to want to see all sub-taxa broken-out for several reasons. It's more interesting, but also they're often searching for something they don't know about. Having the results show organized details from their search - like all the species and sub-species of Sterna listed and displayed distinctly - helps them find what they're looking for, and learn something in the process. I may be missing some features that already do this. If so, I need help to find them. For us to accomplish this, I will take the results of the GBIF auto-suggest API call and break them into taxonKeys for each sub-taxa, then construct a URL query parameter from that list. eg. https://val.vtecostudies.org/gbif-explorer/?taxonKey=9367409&taxonKey=5229230&view=MAP
• One-stop shopping. In the ALA, their BIE does this - a single text box passes your input through a series of filters and look-ups to find their best-guess at what you're looking for. Initially for us, that's 2 things: Common Name and Scientific Name. GBIF doesn't have Common Names for our regional checklist, and I haven't found a utility to locate those and map them to taxonKeys. We hope to add that because the public mostly knows the Common Names of things, and their knowledge is very local.
• People are familiar with this one-box UX, because Google. I think we are conditioned to type our ideas into a box and expect the web to find answers for us.

But we have that all-info text box on the home page, so we can remove it from the gbif-explorer page, I think?

[MortenHofft]

But we have that all-info text box on the home page, so we can remove it from the gbif-explorer page, I think?

I find it confusing, but clearly it is also because you have a need. And it also seem a shame to loose that option once you are in the explorer. In case you want to start a new with a new search.

Custom suggest I have allowed some degree of adding custom filters, we could also experiment with that. A suggest for example could use your own endpoint, but it would have to map to taxonKeys known by the GBIF search API obviously. But you could in theory have your own suggest endpoint (constructed somehow) that allowed the user to type in common names and scientific names, and then suggested that species, along with the common name as well as subspecies. All of which the user could choose from. And selections would then set the appropriate taxonKey filter. But for a suggest it would have to always map to a single parameter, e.g. taxonKey. So it wouldn't sometimes add a taxonKey and sometimes a free text search. If you have your common vernacular names in the checklist, then it should be possible to map those to backbone taxonKeys (assuming that the scientific name is known to GBIF backbone of course)

Omni search bar Yeah I like the idea of that as well. But have postponed it as an add on to the core filters. I cannot quite figure out what I think the behaviour should be either. So it isn't something that is just around the corner. But nice to hear someone else say it.

Is there a working implementation of what you would like somewhere you can point to with a url? Screenshots? Drawings on a napkin? I would like to understand it better and ideally implement something that can support it.

[MortenHofft]

https://github.com/gbif/portal-feedback/issues/4238 aside from being broken, then perhaps this API could be used somehow (assuming it was fixed and your checklist contained vernacular names) https://api.gbif.org/v1/species/search?qField=VERNACULAR&status=ACCEPTED&q=house%20cat&datasetKey=0b1735ff-6a66-454b-8686-cae1cbc732a2

The qField restricts the query q parameter to match on vernacular names. It isn't as fast as the suggest API, but perhaps it could be used in combination somehow?

[jloomisVCE]

I agree this is confusing. There's mayhem behind an omni box.

Thank you for explaining the species search with qField. I was unaware of that feature. I have yet to try to implement it, but I think this will provide us with the vernacularName search we need. We will add vernacularNames to our regional checklist to make those available for this search.

Thanks also for clarifying the distinct issues in my post. I agree with your distinctions. I think there are 3 primary items: Custom Suggest, an Omni Box, and Occurrence Taxa-Breakout. I think there is also a more general item: Species Summary Views. The data-widget exposes views of occurrence data (it does this beautifully). We also want to show summary-views centered on species information: an overview Taxon Profile with Taxonomic Tree. I'm not sure how that should be done.

I have implemented some of these features, and I have thought about how these things should work together, but I haven't tried to assemble them into a coherent system. I should do that. I would enjoy discussing that with you if that's welcome.

I note that your description of a Custom Suggest is what I implemented on our VAL home page (except for the vernacularName lookup): free text is pushed through the species API. If a match is found, it calls the data-widget with ?taxonKey=result. If NO match is found, it calls the data-widget with ?q=text.

Finally, I did create a Beta Leaflet map for our VAL Species Pages that separates taxa into sub-taxa. Here's an example of that for a GENUS: https://vtatlasoflife.org/val_www/leaflet/val_speciespage_leaflet.html?species={%22Calopteryx%22:%22#800000%22} The upper map Key has a list of taxa 'broken'-out into sub-taxa.

[MortenHofft]

I'm afraid we do not really have a way to display species like that currently. But it makes sense.

As for the multiple baselayers. I've stayed away from making this anywhere near GIS product, but there is an option to add your own baselayers using the TileJSON format.

So if you serve this from somewhere then you can reference it

Let us call the tilejson file townsBasemap.json

{
  "version": 8,
  "name": "ESRI towns",
  "metadata": {
    "gb:reproject": false
  },
  "sources": {
    "outline": {
      "type": "geojson",
      "data": "towns.geojson"
    },
    "topo": {
      "type": "raster",
      "tiles": [
        "https://server.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer/tile/{z}/{y}/{x}"
      ],
      "maxzoom": 20,
      "tileSize": 256,
      "attribution": "Tiles © Esri"
    }
  },
  "layers": [
    {
      "id": "background",
      "paint": {
        "background-color": "#e5e9cd"
      },
      "type": "background"
    },
    {
      "id": "base-layer",
      "type": "raster",
      "source": "topo"
    },
    {
      "id": "geojson-layer",
      "type": "line",
      "source": "outline",
      "paint": {
        "line-color": "#00f",
        "line-width": 2
      }
    }
  ],
  "id": "esri-towns"
}

and the towns.geojson is what you have at https://vtatlasoflife.org/val_www/leaflet/geojson/Polygon_VT_Town_Boundaries.geojson

Above specifies a map with 2 layers, the esri layer in bottom and a geojson overlay. This is a standard format called tilejson.

The widget then allows you to add that basemap as an option. In your configuration of the maps https://github.com/VtEcostudies/VAL_GBIF_Wordpress/blob/main/gbif_data_widget.js#L82 you can then add

mapStyles: {
  MERCATOR: ['NATURAL', 'SATELLITE', 'BRIGHT', 'DARK', 'MERCATOR_TOWNS'], // The name of your custom style
  PLATE_CAREE: ['NATURAL', 'BRIGHT', 'DARK']
},
addMapStyles: function ({ mapComponents }) { // Add your custom style
  return {
    MERCATOR_TOWNS: {
      component: mapComponents.OpenlayersMap,
      labelKey: 'Towns', // the label displayed in the layer selector
      mapConfig: {
        basemapStyle: `http://the_place_you_host_your_tilejson.com/townsBasemap.json`,
        projection: 'EPSG_3857'
      }
    }
  }
}

[jloomisVCE]

Thanks, this looks excellent. I will try adding map layers soon.

On the question of an Omni-box search (not a Custom Suggest: just how we handle the raw text when the user hits Enter) I think that actually NOT constraining the api/v1//species/search?q=text to qField=VERNACULARNAME does just what we want: it searches for both scientificName and vernacularName at the same time.

I also think I should NOT use the /species/match endpoint, which only searches for scientificName. However this complicates the search box results because the /species/match endpoint provides a single result, or none.

A solution to this ambiguous search-results problem is to add a species-summary view to display ranked results from a species search. From that species-summary view, users could select species to view occurrence data.

[MortenHofft]

https://api.gbif.org/v1/species/search?q=polar%20bear will search all fields, including descriptions https://api.gbif.org/v1/species/search?q=polar%20bear&qField=VERNACULAR&qField=SCIENTIFIC will search vernacular and scientific names https://api.gbif.org/v1/species/search?q=polar%20bear&qField=VERNACULAR will search vernacular only

[jloomisVCE]

Prototype of species-summary view on a staging site. I removed auto-suggest for testing. Type common or scientific name into 'omni' box. See staging branch.

[MortenHofft]

Nice - it makes sense doing this. And I think you are right. Having that page in the middle is probably the best solution in this case. Do you plan to add matching to other stuff (e.g. gadm localities)?