nokey.science_and_nature package

Submodules

nokey.science_and_nature.integrated_taxonomic_information_system module

class nokey.science_and_nature.integrated_taxonomic_information_system.ITIS(use_caching=False, cache_name='itis_cache', backend='sqlite', expire_after=3600)

Bases: object

A class for interacting with the Integrated Taxonomic Integration System API.

base_url

The base URL of the API.

about

A short description of the API.

get_ITIS_terms(search_key, data_format='json')

Gets a list of ITIS Terms as used by the Resource Catalog Input Tool from a common or scientific name match, or an empty result set if there is no match.

Parameters:

• search_key (str) – The common or scientific name.

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the search key.

Return type:

dict or string (xml)

get_ITIS_terms_from_common_name(search_key, data_format='json')

Gets a list of ITIS Terms as used by the Resource Catalog Input Tool from a common name match, or an empty result set if there is no match.

Parameters:

• search_key (str) – The common name.

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the search key.

Return type:

dict or string (xml)

get_ITIS_terms_from_scientific_name(search_key, data_format='json')

Gets a list of ITIS Terms as used by the Resource Catalog Input Tool from a scientific name match, or an empty result set if there is no match.

Parameters:

• search_key (str) – The scientific name.

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the search key.

Return type:

dict or string (xml)

get_LSID_from_TSN(tsn, data_format='json')

Gets the unique LSID for the TSN, or an empty result if there is no match.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_TSN_from_LSID(tsn, data_format='json')

Gets the TSN corresponding to the LSID, or an empty result if there is no match.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_TSNs_by_vernacular_language(language, data_format='json')

Provide a listing of Taxonomic Serial Numbers (TSNs) with vernaculars entered in the requested language.

Parameters:

• language (str) – The desired language. Supported values are Afrikaans, Arabic, Australian, Bengali, Chinese, Djuka, Dutch, eng, English, Fijan, French, Galibi, German, Greek, Hausa, Hawaiian, Hindi, Icelandic, Iglulik Inuit, Italian, Japanese, Javanese, Khmer, Korean, Lao, Malagasy, Manyika, Native American, Ndau, Northern Sotho, Portuguese, Romanian, Shona, Spanish, Swati, unspecified, Xhosa, Zulu.

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the language.

Return type:

dict or string (xml)

get_accepted_names_from_TSN(tsn, data_format='json')

Returns a list of accepted names for the TSN. This can return more than one result if the TSN is for a synonym.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_any_match_count(search_key, data_format='json')

Returns a count of the matches found by comparing the search key to the ITIS common names, scientific names, and TSNs..

Parameters:

• search_key (str or int) – The name (common or scientific) or Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the count matching the search key.

Return type:

dict or string (xml)

get_comment_detail_from_TSN(tsn, data_format='json')

Returns the list of comments for the TSN. This can return more than result if multiple comments are entered.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_common_names_from_TSN(tsn, data_format='json')

Returns a list of common names for the TSN.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_core_metadata_from_TSN(tsn, data_format='json')

Returns the set of core metadata for the TSN. This contains credibility rating, taxonomic usage, unacceptability reason, coverage, and currency data.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_coverage_from_TSN(tsn, data_format='json')

Returns the taxon coverage information for the TSN. This information is available for Genus and above (rank_id > 190) only.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_credibility_rating_from_TSN(tsn, data_format='json')

Returns the credibility rating for the TSN.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_credibility_ratings(data_format='json')

Provides a list of all the unique valid credibility rating values contained in the database.

Parameters:

data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the credibility rating values.

Return type:

dict or string (xml)

get_currency_from_TSN(tsn, data_format='json')

Returns the taxon currency information for the TSN. This information is available for Genus and above (rank_id > 190) only.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_date_data_from_TSN(tsn, data_format='json')

Returns the initial time stamp and last update date for the TSN.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_description(data_format='json')

Provides a description of the web service and the ITIS database.

Parameters:

data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing a description of the ITIS database.

Return type:

dict or string (xml)

get_docs_url()

Returns the URL for the ITIS API documentation.

Parameters:

None –

Returns:

The URL for the API docs.

Return type:

string

get_experts_from_TSN(tsn, data_format='json')

Returns a list of the expert information for the TSN.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_full_hierarchy_from_TSN(tsn, data_format='json')

Returns the Taxonomic Hierarchy from the kingdom to the requested scientific name, and the immediate children of the scientific name.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_full_record_from_LSID(tsn, data_format='json')

Returns the full ITIS record for the TSN in the LSID, found by comparing the TSN in the search key to the TSN field. Returns an empty result set if there is no match or the TSN is invalid.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_full_record_from_TSN(tsn, data_format='json')

Returns the full ITIS record for a TSN found by comparing the search key to the TSN field, or an empty result set if there is no match.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_geographic_divisions_from_TSN(tsn, data_format='json')

Returns a list of the geographic divisions for the TSN.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_geographic_values(data_format='json')

Provides a list of all the geographic values contained in the database.

Parameters:

data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the geographic values contained in the database.

Return type:

dict or string (xml)

get_global_species_completeness_from_TSN(tsn, data_format='json')

Returns the taxon completenes rating for the TSN.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_hierarchy_down_from_TSN(tsn, data_format='json')

Returns a list of all the valid/accepted scientific names contained within a particular valid/accepted scientific name and their TSNs, limited to immediate children only. The result set will be found by comparing the search key to the parent TSN field.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_hierarchy_up_from_TSN(tsn, data_format='json')

Returns the parent of the TSN (i.e. the parent of the current scientific name in the taxonomic hierarchy) found by comparing the search key to the ITIS TSN field.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_jurisdiction_values(data_format='json')

Provides a list of all the jurisdiction values contained in the database.

Parameters:

data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the jurisdiction values contained in the database.

Return type:

dict or string (xml)

get_jurisdictional_origin_from_TSN(tsn, data_format='json')

Returns a list of the jurisdiction and origin values for the TSN.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_jurisdictional_origin_values(data_format='json')

Provides a list of all the origin values contained in the database.

Parameters:

data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the origin values contained in the database.

Return type:

dict or string (xml)

get_kingdom_name_from_TSN(tsn, data_format='json')

Returns the kingdom name for the TSN.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_kingdom_names(data_format='json')

Provides a list of all the unique kingdom names contained in the database, their kingdom IDs and their TSNs.

Parameters:

data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the kingdom names contained in the database.

Return type:

dict or string (xml)

get_last_change_date(data_format='json')

Provides the date the ITIS database was last updated.

Parameters:

data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the date the database was last updated.

Return type:

dict or string (xml)

get_other_sources_from_TSN(tsn, data_format='json')

Returns a list of the other sources used for the TSN.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_parent_TSN_from_TSN(tsn, data_format='json')

Returns the parent TSN for the entered TSN.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_publications_from_TSN(tsn, data_format='json')

Returns a list of the pulications used for the TSN.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_rank_names(data_format='json')

Provides a list of all the unique rank names contained in the database and their kingdom and rank ID values.

Parameters:

data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing a list of all the unique rank names contained in the database.

Return type:

dict or string (xml)

get_record_from_LSID(tsn, data_format='json')

Gets the partial ITIS record for the TSN in the LSID, found by comparing the TSN in the search key to the TSN field. Returns an empty result set if there is no match or the TSN is invalid.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_review_year_from_TSN(tsn, data_format='json')

Returns the review year for the TSN.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_scientific_name_from_TSN(tsn, data_format='json')

Returns the scientific name for the TSN. Also returns the component parts (names and indicators) of the scientific name.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_synonym_names_from_TSN(tsn, data_format='json')

Returns a list of the synonyms (if any) for the TSN.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_taxon_authorship_from_TSN(tsn, data_format='json')

Returns the author information for the TSN.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_taxonomic_rank_name_from_TSN(tsn, data_format='json')

Returns the kingdom and rank information for the TSN.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_taxonomic_usage_from_TSN(tsn, data_format='json')

Returns the usage information for the TSN.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_unacceptability_reason_from_TSN(tsn, data_format='json')

Returns the unacceptability reason, if any, for the TSN.

Parameters:

• tsn (int) – The Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the TSN.

Return type:

dict or string (xml)

get_vernacular_languages(data_format='json')

Provides a list of the unique languages used in the vernacular table.

Parameters:

data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing a list of all the unique languages used in the vernacular table.

Return type:

dict or string (xml)

search_by_common_name(search_key, data_format='json')

Returns matches found by comparing the search key to the ITIS common names.

Parameters:

• search_key (str) – The common name.

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the search key.

Return type:

dict or string (xml)

search_by_common_name_begins_with(search_key, data_format='json')

Return matches found by comparing the search key to the beginning of the ITIS common names.

Parameters:

• search_key (str) – The beginning of the name to be searched.

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the search key.

Return type:

dict or string (xml)

search_by_common_name_ends_with(search_key, data_format='json')

Return matches found by comparing the search key to the end of the ITIS common names.

Parameters:

• search_key (str) – The end of the name to be searched.

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the search key.

Return type:

dict or string (xml)

search_by_scientific_name(search_key, data_format='json')

Returns matches found by comparing the search key to the ITIS scientific names.

Parameters:

• search_key (str) – The scientific name.

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the search key.

Return type:

dict or string (xml)

search_for_any_match(search_key, data_format='json')

Returns matches found by comparing the search key to the ITIS common names, scientific names, and TSNs.

Parameters:

• search_key (str or int) – The name (common or scientific) or Taxonomic Serial Number (TSN).

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the search key.

Return type:

dict or string (xml)

search_for_any_match_paged(search_key, page_size=50, page_num=1, ascend=True, data_format='json')

Returns matches found by comparing the search key to the ITIS common names, scientific names, and TSNs.

Parameters:

• search_key (str or int) – The name (common or scientific) or Taxonomic Serial Number (TSN).

• page_size (int) – Number of matches returned per page. Defaults to 50.

• page_num (int) – The page number to return (pagination). Defaults to the first page.

• ascend (boolean) – Whether to sort pages in ascending or descending alphabetical order. Default is True.

• data_format (str) – The desired format for returned data. Defaults to json, but other option is xml.

Returns:

A dictionary or XML string containing the data matching the search key.

Return type:

dict or string (xml)

nokey.science_and_nature.nobel_prize module

class nokey.science_and_nature.nobel_prize.NobelPrizeAPI(use_caching=False, cache_name='nobel_prize_cache', backend='sqlite', expire_after=3600)

Bases: object

A class to interact with the Nobel Prize API.

base_url

The base url for the Nobel Prize API.

about

A short description of the API.

get_all_nobel_prizes()

Returns a list of all the Nobel Prizes award along with information about the specific prize and winners.

Parameters:

None –

Returns

dict: A dictionary containing a list of Nobel Prizes awarded and relevant information about the prize.

get_docs_url()

Returns the URL for the Nobel Prize API documentation.

Parameters:

None –

Returns:

The URL for the Nobel Prize API docs.

Return type:

string

get_nobel_laureate_by_id(laureateID)

Returns a specific Nobel Prize and information about the specific prize and winners.

Parameters:

laureateID (int) – A unique identifier for a specific Nobel laureate.

Returns

dict: A dictionary containing a specific Nobel Prize awarded and relevant information about the prize.

get_nobel_prize_laureates()

Returns a list of Nobel Prize laureates with information about the winners.

Parameters:

None –

Returns

dict: A dictionary containing a list of Nobel Prize laureates and relevant information about the winners.

get_one_nobel_prize(category, year)

Returns a specific Nobel Prize and information about the specific prize and winners.

Parameters:

• category (str) – The category of the prize awarded. Possible values are che (chemistry), eco (economic sciences), lit (literature), pea (peace), phy (physics), and med (medicine). Any other strings passed for category will return all the pieces for specified year.

• year (int) – The year the prize was awarded.

Returns

dict: A dictionary containing a specific Nobel Prize awarded and relevant information about the prize.

Module contents