🦋 EcoObs

Unified access to biodiversity occurrence records from multiple providers.

Part of the EcoToolBox ecosystem 🌿

---

✨ Overview

EcoObs is a Python library for retrieving species occurrence records from the world's leading biodiversity databases through a single, unified interface.

Instead of querying multiple APIs independently, EcoObs automatically combines occurrence records from different providers into a single dataset, simplifying biodiversity research and Species Distribution Modeling workflows.

Currently supported providers:

• 🌍 GBIF
• 📸 iNaturalist
• 🌱 SpeciesLink

---

🚀 Features

• 🌎 Unified API for multiple biodiversity providers
• 🦋 Species occurrence retrieval
• 🌍 Country filtering
• 📅 Year filtering
• 📍 Geographic bounding box filtering
• 🧬 Species name autocomplete
• 🐍 Simple Python API
• 📊 Returns Pandas DataFrames

---

📦 Installation

pip install ecoobs

---

⚡ Quick Start

import ecoobs

ecoobs.save_gbif_credentials(
    user="username",
    email="email@example.com",
    pwd="password"
)

ecoobs.save_specieslink_apikey("YOUR_API_KEY")

df = ecoobs.get_occurrences(
    ["Panthera onca"]
)

print(df.head())

---

📚 Examples

Search by species

df = ecoobs.get_occurrences(
    ["Panthera onca"]
)

---

Search within a country

df = ecoobs.get_occurrences(
    ["Panthera onca"],
    country="Brazil"
)

---

Search by year range

df = ecoobs.get_occurrences(
    ["Panthera onca"],
    year_range=(2000, 2025)
)

---

Retrieve only GBIF records

df = ecoobs.get_occurrences(
    ["Panthera onca"],
    includeGbif=True,
    includeInaturalist=False,
    includeSpeciesLink=False
)

---

📖 Supported Providers

Provider	Description
GBIF	Global Biodiversity Information Facility
iNaturalist	Citizen science observations
SpeciesLink	Brazilian biodiversity network

---

🔄 Workflow

Scientific Name
        │
        ▼
      EcoObs
        │
 ┌──────┼────────┐
 │      │        │
 ▼      ▼        ▼
GBIF iNaturalist SpeciesLink
 │      │        │
 └──────┼────────┘
        ▼
 Combined DataFrame
        ▼
 Analysis / SDM / Visualization

---

🌿 EcoToolBox Ecosystem

Project	Description
🖥️ EcoLab	Species Distribution Modeling
🌍 EcoEnv	Environmental variables
🦋 EcoObs	Species occurrence records
🌿 EcoInteract	Ecological interactions

---

📄 Citation

If EcoObs contributes to your research, please cite this software.

---

🤝 Contributing

Pull requests are welcome.

Bug reports and feature requests are encouraged.

---

📜 License

MIT License.