Species data stored into the Regional Flora database can be searched and retrieved by external programs through a specific Web Service interface. This page describes such interface and is therefore targeted to web developers. The interface follows the REST pattern, with all requests specified as simple URLs accessed through HTTP GET with a number of parameters. Responses are always returned in JSON format with strings encoded in UTF-8. All requests start with the "/ws/1.0/" prefix, preceded or not by a language code.
Metadata about the web service can be retrieved by calling the root address:
Metadata response includes general information about the web service, such as name, citation, license, settings, available languages and dictionaries containing controlled vocabulary that can be used on searches or referenced by search results:
{
"license": "GNU AGPLv3",
"name": "Regional Flora Web Service",
"settings": {
"species_pagination": {
"default_per_page": 25,
"max_per_page": 100,
"min_per_page": 10
}
},
"dictionaries": {
"color": {
1: "white",
2: "red",
3: "yellow"
}
},
"languages": {
"en": "English",
"pt-br": "Brazilian Portuguese"
},}
Most of the content returned by the web service is associated with a language. Such content can in principle be expressed in any of the available languages indicated by the metadata response. To retrieve content in a specific language, prepend the language code to the root URL, such as:
If no language is specified, the service returns content in the default language. Please note that if a particular content is not translated in the system, it will always be returned in the default language. In this case, users can contact the system administrators asking for the missing translations.
Many identifiers are returned by the web service - some of them are hard coded into the system, others are primary keys that are automatically assigned to new content. In both cases, the system itself does not ensure that identifiers may remain the same over the time, since this is essentially a management matter (records can be removed, categories can be changed, etc.). For this reason, external applications are recommended to either interact with the service dynamically (always getting content on-the-fly), or, if they wish to work with local copies, then avoid storing only partial content.
Species can be searched or listed by appending "/sp/" to the root URL and using any of the optional search parameters. To start listing all species, simply use:
The number of records returned can be specified with the "per_page" parameter:
The "per_page" parameter must be a number between the "min_per_page" and "max_per_page" values indicated in the web service metadata. When "per_page" is not specified, the "default_per_page" value is used. Next pages can be fetched using the "page" parameter.
Search responses are always an array of records, each record containing species full name, id and link to its web page on the system, such as:
[
{
"fullname": "Actinostemon klotzschii (Didr.) Pax",
"id": 17,
"link": "http://flora.ipe.org.br/sp/17"
},
{
"fullname": "Allophylus edulis (A.St.-Hil. et al.) Hieron. ex Niederl.",
"id": 18,
"link": "http://flora.ipe.org.br/sp/18"
},
{
"fullname": "Amaioua intermedia Mart. ex Schult. & Schult.f.",
"id": 19,
"link": "http://flora.ipe.org.br/sp/19"
}
]
Pagination links are included in the Link header so that clients don't need to build links during data harvesting, such as:
Link: <http://flora.ipe.org.br/ws/1.0/sp?page=2>; rel="next",
<http://flora.ipe.org.br/ws/1.0/sp?page=25>; rel="last"
The possible "rel" values are:
| next | Shows the URL of the immediate next page of results. |
| last | Shows the URL of the last page of results. |
| first | Shows the URL of the first page of results. |
| prev | Shows the URL of the immediate previous page of results. |
The following parameters can be used to filter species by recommended use. Presence of the parameter - regardless its value - is enough to activate the filter.
| parameter | recommended use |
|---|---|
| restor | Restoration |
| urban | Urban forestry |
| silv | Silviculture |
Examples:
Species recommended for silviculture: /ws/1.0/sp?silv
Species recommended for silviculture and urban forestry: /ws/1.0/sp?silv&urban
Species can also be searched by name using the "name" parameter. In this case, searches are performed against scientific names, popular names and synonyms. The search engine initially tries an exact match. Upon failure, then it tries a partial match with the beginning of all names. If it fails again, then it tries a partial match with any part of all names.
Example:
| filter | parameter | description | accepted values | notes |
|---|---|---|---|---|
| Family | family | Species family. | string (complete family name) | |
| Endemism | endemic | If the species is considered endemic. | - (presence of the parameter) | |
| Rarity | rare | If the species is considered rare. | - (presence of the parameter) | |
| Special features | h_flowers | If flowers are considered a special feature. | - (presence of the parameter) | joined by AND |
| h_leaves | If leaves are considered a special feature. | - (presence of the parameter) | ||
| h_fruits | If fruits are considered a special feature. | - (presence of the parameter) | ||
| h_crown | If crown is considered a special feature. | - (presence of the parameter) | ||
| h_bark | If bark is considered a special feature. | - (presence of the parameter) | ||
| h_seeds | If seeds are considered a special feature. | - (presence of the parameter) | ||
| h_wood | If wood is considered a special feature. | - (presence of the parameter) | ||
| h_roots | If roots are considered a special feature. | - (presence of the parameter) | ||
| Growth | gr_slow | Slow. | - (presence of the parameter) | joined by OR |
| gr_moderate | Moderate. | - (presence of the parameter) | ||
| gr_fast | Fast. | - (presence of the parameter) | ||
| Trunk alignment | tr_straight | Straight. | - (presence of the parameter) | joined by OR |
| tr_sl_inclined | Slightly inclined. | - (presence of the parameter) | ||
| tr_inclined | Inclined. | - (presence of the parameter) | ||
| tr_sl_crooked | Slightly crooked. | - (presence of the parameter) | ||
| tr_crooked | Crooked. | - (presence of the parameter) | ||
| Foliage persistence | fo_evergreen | Evergreen. | - (presence of the parameter) | joined by OR |
| fo_semideciduous | Semideciduous. | - (presence of the parameter) | ||
| fo_deciduous | Deciduous. | - (presence of the parameter) | ||
| Height | min_height | Minimum height (m). | numeric | |
| max_height | Maximum height (m). | numeric | ||
| DBH | min_dbh | Minimum DBH (cm). | numeric | |
| max_dbh | Maximum DBH (cm). | numeric | ||
| Crown diameter | cr_min_diameter | Minimum crown diameter (m). | numeric | |
| cr_max_diameter | Maximum crown diameter (m). | numeric | ||
| Germination rate | seed_gmin_rate | Minimum rate (%). | numeric | |
| seed_gmax_rate | Maximum rate (%). | numeric | ||
| Crown shape | cr_shape | Desired crown shape. | character | single value (see "crown_shape" in the dictionaries metadata for valid values) |
| Flower color | color | Desired flower color. | digit | single value (see "color" in the dictionaries metadata for valid values) |
| Root system | r_type | Desired root type. | character | single value (see "root_type" in the dictionaries metadata for valid values) |
| Seed type | s_type | Desired seed type. | character | single value (see "seed_type" in the dictionaries metadata for valid values) |
| Light requirements | light | Desired light requirements. | character | single value (see "light_requirement" in the dictionaries metadata for valid values) |
| Flowering period | fl_start | Start of the flowering period. | integer | |
| fl_end | End of the flowering period. | integer | ||
| Fruiting period | fr_start | Start of the fruiting period. | integer | |
| fr_end | End of the fruiting period. | integer | ||
| Pruning | pruning | Requires pruning. | boolean | 0 or 1 |
| Pollinators | pollinators | Attracts pollinators. | boolean | 0 or 1 |
| Diseases | diseases | Vulnerable to pests or diseases. | boolean | 0 or 1 |
| Thorns | thorns | Contains thorns or spines. | boolean | 0 or 1 |
| Toxic | toxic | Is toxic or allergenic. | boolean | 0 or 1 |
| Successional group | sg_pioneer | Pioneer. | - (presence of the parameter) | joined by OR |
| sg_early_secondary | Early secondary. | - (presence of the parameter) | ||
| sg_late_secondary | Late secondary. | - (presence of the parameter) | ||
| sg_climax | Climax. | - (presence of the parameter) | ||
| Seed dispersal | dt_anemochorous | Anemochorous. | - (presence of the parameter) | joined by OR |
| dt_autochorous | Autochorous. | - (presence of the parameter) | ||
| dt_barochorous | Barochorous. | - (presence of the parameter) | ||
| dt_hydrochorous | Hydrochorous. | - (presence of the parameter) | ||
| dt_zoochorous | Zoochorous. | - (presence of the parameter) | ||
| Terrain drainage | wetland | Adapted to wetlands. | - (presence of the parameter) | joined by OR |
| dry | Adapted to dry terrains. | - (presence of the parameter) | ||
| Pre-germination treatment | pg_no_need | No need for treatment. | - (presence of the parameter) | joined by OR |
| pg_thermal | Thermal treatment. | - (presence of the parameter) | ||
| pg_chemical | Chemical treatment. | - (presence of the parameter) | ||
| pg_water | Water treatment. | - (presence of the parameter) | ||
| pg_mechanical | Mechanical treatment. | - (presence of the parameter) | ||
| pg_combined | Combined methods. | - (presence of the parameter) | ||
| pg_other | Other methods. | - (presence of the parameter) | ||
| Symbiotic association | symb_assoc | Has symbiotic association. | boolean | 0 or 1 |
| Specific uses | uses | Documented uses for the species (see "use" in the dictionaries metadata for valid ids). | digit | multiple parameters accepted |
| Habitat | habitats | Species habitats (see "habitat" in the dictionaries metadata for valid ids). | digit | multiple parameters accepted |
| Wood density | min_density | Minimum density (kg/m3). | numeric | |
| max_density | Maximum density (kg/m3). | numeric | ||
| MAI curve | has_mai_curve | Has MAI curve. | boolean | 0 or 1 |
| Conservation status | status | Conservation status. | text | exact match (see "conservation_status" in the dictionaries metadata for valid values). |
More details about a particular species can be retrieved by appending the species id to the URL, such as:
By default, only a basic subset of the species data is returned, including full name, common names, synonyms and family:
{
"common_names": [
"Folha-fedorenta"
],
"family": "Euphorbiaceae",
"fullname": "Actinostemon klotzschii (Didr.) Pax",
"synonyms": [
"Actinostemon angustifolius (Müll.Arg.) Pax",
"Actinostemon estrellensis Pax"
]
}
If there is no species associated with the id an HTTP 404 code (not found) is returned. To include additional data for the species, additional parameters can be used, as explained in the next sections.
Use the "points" parameter to include species occurrence points. Example:
Basic data and species occurrence points: /ws/1.0/sp/18?points
{
"family": "Sapindaceae",
"fullname": "Allophylus edulis (A.St.-Hil. et al.) Hieron. ex Niederl.",
"points": [
{
"label": "Parcela 1",
"x": -46.50867222222222,
"y": -23.330716666666667
},
{
"label": "Parcela 4",
"x": -46.489625000000004,
"y": -23.12713888888889
},
{
"label": "Parcela 5",
"x": -46.528216666666665,
"y": -23.168808333333335
},
]
}
Use the "features" parameter to include general features about the species. Example:
Basic data and species general features: /ws/1.0/sp/18?features
{
"family": "Sapindaceae",
"features": {
"bark": {
"texture": "R"
},
"crown": {
"diameter": {
"max": 7,
"min": 4
},
"shape": {
"classification": "S"
}
},
"flower": {
"color": 1
},
"fruit": {
"type": "B"
},
"growth": {
"details": "Aos 12 meses de idade pode alcan\u00e7ar 30-50 cm de altura.",
"rate": [
"S",
"M"
]
},
"leaves": {
"foliage_persistence": [
"S"
]
},
"root": {
"type": "T"
},
"size": {
"dbh": {
"max": "30.0",
"min": "20.0"
},
"height": {
"max": "20.0",
"min": "6.0"
}
},
"trunk": {
"alignment": [
"5"
]
}
},
"fullname": "Allophylus edulis (A.St.-Hil. et al.) Hieron. ex Niederl."
}
Use the "care" parameter to include information about particular care with the species. Example:
Basic data and information about care: /ws/1.0/sp/18?care
{
"care": {
"pruning": {
"indication": true
}
},
"family": "Sapindaceae",
"fullname": "Allophylus edulis (A.St.-Hil. et al.) Hieron. ex Niederl."
}
Use the "ecology" parameter to include information about ecology and reproduction. Example:
Basic data and information about ecology: /ws/1.0/sp/18?ecology
{
"ecology": {
"dispersers": {
"information": "Aves/ bugio (Alouatta guariba)"
},
"flowering": {
"period": {
"end": 9,
"start": 7
}
},
"fruiting": {
"period": {
"end": 12,
"start": 10
}
},
"pollinators": {
"information": "Abelhas"
},
"seed_dispersal": {
"classification": [
"2",
"5"
]
},
"successional_group": {
"classification": [
"1",
"2"
]
}
},
"family": "Sapindaceae",
"fullname": "Allophylus edulis (A.St.-Hil. et al.) Hieron. ex Niederl."
}
Use the "seedling" parameter to include information about seedling production. Example:
Basic data and information about seedling production: /ws/1.0/sp/18?seedling
{
"family": "Sapindaceae",
"fullname": "Allophylus edulis (A.St.-Hil. et al.) Hieron. ex Niederl."
"seedling_production": {
"germination": {
"rate": {
"max": 96,
"min": 44
},
"time_lapse": {
"max": 45,
"min": 8
}
},
"light": {
"requirements": "S"
},
"pre_germination_treatment": {
"treatment": [
"N"
]
},
"seed_collection": {
"details": "Momento de colheita: quando iniciarem queda espont\u00e2nea."
},
"seed_type": {
"type": "O"
},
"seedling_production": {
"details": "Semeadura direta das sementes ou dos frutos.",
"individual_containers": true,
"seedbed": true
},
"seeds_per_weight": {
"value": 400
}
}
}
Use the "silviculture" parameter to include information about silviculture. Example:
Basic data and information about silviculture: /ws/1.0/sp/18?silviculture
{
"family": "Sapindaceae",
"fullname": "Allophylus edulis (A.St.-Hil. et al.) Hieron. ex Niederl."
"silviculture": {
"has_mai_curve": true,
"wood_density": 1.5,
"wood_information": "(detalhes sobre a madeira)"
}
}
Use the "references" parameter to include bibliographic references. Example:
Basic data, information about care and bibliographic references: /ws/1.0/sp/18?care&references
{
"care": {
"pruning": {
"indication": true,
"references": [
"1"
]
}
},
"family": "Sapindaceae",
"fullname": "Allophylus edulis (A.St.-Hil. et al.) Hieron. ex Niederl."
"references": {
"1": "Esp\u00e9cies Arb\u00f3reas Brasileiras, v.2",
"2": "Manual T\u00e9cnico de Arboriza\u00e7\u00e3o Urbana (RS)",
"3": "Manual T\u00e9cnico de Arboriza\u00e7\u00e3o Urbana de S\u00e3o Paulo",
"4": "KUHLMAN, 1975",
"5": "Plantas da Floresta Atl\u00e2ntica",
"6": "Backes; Irgang, 2004",
"7": "ENGEL; POGGIANI, 1985",
"8": "Gimenez; Moglia, 2003",
"9": "Campos, 2007",
"10": "POGGIANI, 1985",
"11": "AQUILA; AZAMBUJA, 1996",
"12": "EIBL et al., 1994",
"13": "Sanchonete, 1989",
"14": "Publica\u00e7\u00e3o Biondi",
"15": "Lorenzi v.1",
"16": "anexo Resolu\u00e7\u00e3o SMA 08",
"17": "Circular t\u00e9cnica 127, Embrapa Florestas",
"18": "Rev. Arv. 30, n.6",
"19": "LORENZI e SALIS et al., 1994",
"20": "VACCARO et al., 1999",
"21": "Reitz, 1980"
}
}