Serviço Web da Flora Regional

Informações Gerais

Dados de espécies armazenados no banco de dados da Flora Regional podem ser acessados por aplicativos externos através de uma interface do tipo serviço web. Esta página descreve a interface e está portanto voltada a desenvolvedores de aplicativos web. A interface segue o padrão REST, com requisições formuladas em simples URLs invocadas com HTTP GET e parâmetros pré-definidos. As respostas são sempre formatadas no padrão JSON e codificadas em UTF-8. Todas as requisições começam com o prefixo "/ws/1.0/", precedido ou não por um código de língua para o conteúdo.

Metadados do serviço

Metadados sobre o serviço podem ser obtidos acessando-se o endereço raíz:

/ws/1.0/

A resposta inclui informações gerais sobre o serviço, tais como nome, citação, licença, configurações, línguas disponíveis e dicionários de vocabulário controlado utilizados nas buscas ou referenciados pelo conteúdo das respostas:

{
    "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"
    },}

Línguas

Grande parte do conteúdo provido pelo serviço está atrelado a uma língua e pode em princípio ser expressado em qualquer uma das línguas disponíveis conforme indicado nos metadados. Para retornar conteúdo numa língua específica, deve-se acrescentar o código da língua antes da URL raíz do serviço:

/en/ws/1.0/

Quando nenhuma língua é especificada, o serviço retorna conteúdo na língua "default" em que está configurado o sistema. Observe que se um conteúdo em particular não estiver traduzido no sistema, ele sempre aparecerá na língua "default". Neste caso, pode-se entrar em contato com os administradores do sistema solicitando a tradução que falta.

Identificadores

Diversos identificadores são retornados pelo serviço - alguns estão fixos no código do programa, outros são chaves primárias criadas automaticamente quando novo conteúdo é adicionado ao sistema. Em ambos os casos, o sistema não garante que os identificadores permanecerão os mesmos ao longo do tempo, uma vez que se trata essencialmente de uma questão de gerenciamento do sistema (registros podem ser removidos, categorias podem ser alteradas, etc.). Por este motivo, aplicativos externos devem preferencialmente interagir dinamicamente com o serviço (em tempo real), ou, caso trabalhem com cópias locais, devem evitar armezenar conteúdo parcial - todas as referências devem ser armazenadas localmente para evitar inconsistências se houver mudança no conteúdo do sistema.

Buscando e listando espécies

Espécies podem ser buscadas ou listadas acrescentando-se "/sp/" no endereço raíz e utilizando-se qualquer um dos parâmetros opcionais de busca. Para loistar todas as espécies, basta usar:

/ws/1.0/sp

O número de registros retornados pode ser especificado com o parâmetro "per_page":

/ws/1.0/sp?per_page=3

O parâmetro "per_page" deve ser um número entre "min_per_page" e "max_per_page" indicados nos metadados do serviço. Quando "per_page" não é especificado, o valor de "default_per_page" é utilizado. As próximas páginas podem ser acessadas através do parâmetro "page".

O resultado das buscas é sempre uma sequência de registros, cada um contendo o nome completo da espécie, seu identificador e um link para sua página no sistema, tal como:

[
    {
        "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"
    }
]

Links de paginação são automaticamente incluídos no header Link para facilitar:

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"

Os possíveis valores de "rel" são:

Filtros

Por recomendação de uso

Os parâmetros seguintes podem ser usados para filtrar espécies por uso recomendado. A presença de cada parâmetro - independente de valor - é suficiente para ativar o respectivo filtro.

Exemplos:

Espécies recomendadas para silvicultura: /ws/1.0/sp?silv

Espécies recomendadas para silvicultura e arborização urbana: /ws/1.0/sp?silv&urban

Por nome

As buscas também podem ser feitas por nome através do parâmetro "name". Neste caso, as buscas são feitas considerando-se nomes científicos, populares e sinônimos. O mecanismo de busca procura inicialmente uma correspondência exata. Caso não consiga, tenta-se uma correspondência parcial com o começo de todos os nomes. Falhando-se novamente, procura-se uma correspondência parcial em qualquer lugar de todos os nomes.

Exemplo:

/ws/1.0/sp?name=casearia

Outros filtros

Obtendo mais informações sobre uma espécie

Mais detalhes sobre uma determinada espécie podem ser obtidos acrescentando-se o identificador da espécie à URL, tal como:

/ws/1.0/sp/17

Neste caso, apenas um subconjunto básico de dados é retornado, incluindo nome completo, nomes populares, sinônimos e família:

{
    "common_names": [
        "Folha-fedorenta"
    ], 
    "family": "Euphorbiaceae", 
    "fullname": "Actinostemon klotzschii (Didr.) Pax", 
    "synonyms": [
        "Actinostemon angustifolius (Müll.Arg.) Pax", 
        "Actinostemon estrellensis Pax"
    ]
}

Se não houver nenhuma espécie associada ao identificador, um erro HTTP 404 (não encontrado) é retornado. Para incluir mais dados sobre a espécie, utilize os parâmetros adicionais descritos à seguir.

Pontos de ocorrência

Utilize o parâmetro "points" para incluir pontos de ocorrência associados à espécie (caso existam). Exemplo:

Dados básicos e pontos de ocorrência: /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
        }, 
    ]
}

Características gerais

Utilize o parâmetro "features" para incluir características gerais da espécie. Exemplo:

Dados básicos e características gerais: /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."
}

Cuidados

Utilize o parâmetro "care" para incluir dados sobre cuidados com a espécie. Exemplo:

Dados básicos e cuidados com a espécie: /ws/1.0/sp/18?care

{
    "care": {
        "pruning": {
            "indication": true
        }
    }, 
    "family": "Sapindaceae", 
    "fullname": "Allophylus edulis (A.St.-Hil. et al.) Hieron. ex Niederl."
}

Ecologia & Reprodução

Utilize o parâmetro "ecology" para incluir dados de ecologia e reprodução. Exemplo:

Dados básicos e dados de ecologia e reprodução: /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."
}

Produção de mudas

Utilize o parêmetro "seedling" para incluir dados sobre produção de mudas. Exemplo:

Dados básicos e dados sobre produção de mudas: /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
        }
    }
}

Silvicultura

Utilize o parâmetro "silviculture" para incluir dados silviculturais sobre a espécie. Exemplo:

Dados básicos e dados silviculturais: /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)"
    }
}

Referências bibliográficas

Utilize o parâmetro "references" para incluir referências bibliográficas. Exemplo:

Dados básicos, cuidados e referências bibliográficas: /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"
    }
}