Name Matching REST API

The most powerful way to query the name matching service is via the GraphQL API however for some applications a very simple REST service is sufficient. That is what is provided here. This service should be seen as a chopped down version of the GraphQL API. Behind the scenes it uses the same code. If you need more complex behaviour you are encouraged to explore the GraphQL API which can be called without the use of client side libraries if necessary.

Test Form

Use this form to test how name strings are parsed and matched.

Requests and Responses

Only GET requests are supported. All parameters are optional. Calling without the "input_string" parameter will return this page. All requests that provide a value in the "input_string" parameter will be responded to with a JSON object equivalent to the taxonNameMatch response object provided by the GraphQL API.

Request Parameters

• input_string The name string to be searched for. It should contain a single botanical name. This should include the authors of the name if available. It should be URL encoded.
• fuzzy_names If an integer value greater than 0 is provided then it will be used as a maximum Levenshtein distance when matching words in the name. Each word parsed from a name (not forming part of the authors string or a rank) is checked against the index. If it doesn't exist then an attempt will be made to find a replacement word that is used in the index and that is within this Levenshtein distance. If a single, unambiguous word is found then that is used in place of the word provided. This helps increase matches when there are typographical/OCR errors of a few characters in complex words. It is recommended not to set this above 3.
• fuzzy_authors If an integer value greater than 0 is provided then it will be used as the maximum Levenshtein distance that two authors strings can be apart and still be considered to match. Unlike with fuzzy_names this is applied to the whole string not words within the string thus catching punctuation and spacing errors.
• check_homonyms If present with the value "true" then homonyms will be checked for. If a single, exact match of name and author string is found but there are other names with the same letters but a different author strings present the match won't be considered unambiguous.
• check_rank If present with the value "true" then the rank will be checked for. If a precise match of name and author string is found and it is possible to extract the rank from the name string but the rank isn't the same the match won't be considered unambiguous.
• accept_single_candidate If present with the value "true" and only a single candidate name is found that will be made the match, even though it isn't an exact match.

Response

A JSON object is returned with the following properties

• inputString (string) The string provided in the input_string parameter.
• searchString (string) The cleaned up input string used for matching.
• match (name object) An unambiguous match. Null if an unambiguous match couldn't be found.
• candidates (array of name objects) An array of name objects that are close matches but not unambiguous.
• method (string) The name of the matching method used internally.
• error (bool) True if there was an error to report.
• error (string) The error message should an error have occured.
• narrative (array of strings) An explanation of the steps taken to parse the name and match it to the index. This is useful for debugging or explaining to the user what happened!

The name objects will have the following properties.

• wfo_id The WFO ID that should be used to refer to this name.
• full_name_plainThe full name (including authors) as plain text.
• full_name_htmlThe full name (including authors) with markup text.
• placementThis is a "sanity check". If the name is placed in the current classification it is the path of names from the root of the taxonomy. If it is unplaced the value will either be UNPLACED (not yet placed by expert) or DEPRECATED (declared unplaceable).

If you would like more complex information back about the name and its placement in different classifications you are encouraged to use the GraphQL API or you could call the names Stable URI to get a JSON representation of it.

Examples

Perfect match

http://rhakhis.rbge.info/matching_rest.php?input_string=Rhopalocarpus+alternifolius+(Baker)+Capuron

Imperfect match

http://rhakhis.rbge.info/matching_rest.php?input_string=Rhopalocarpus+alternifolius+(Baker)+Capuron

GraphQL equivalent

This is an example of a similar matching call using a GraphQL query. It could be extended to include appropriate parts of the graph of TaxonName and TaxonConcept objects as required.

query {
  taxonNameMatch(inputString: "Rhopalocarpus alternifolium (Baker) Capuro") {
    inputString
    searchString
    match {
      wfoId
      fullNameStringPlain
      fullNameStringHtml
    }
    candidates {
      wfoId
      fullNameStringPlain
      fullNameStringHtml
    }
    narrative
  }
}