ALA API MCP Server

# ALA API Endpoints Reference This document lists all publicly available endpoints from the Atlas of Living Australia Biocache Web Services API. ## API Documentation - **OpenAPI Specification**: https://biocache.ala.org.au/ws/v3/api-docs - **Swagger UI**: https://biocache.ala.org.au/ws/swagger-ui/index.html - **Base URL**: `https://biocache-ws.ala.org.au/ws` - **Total Records**: 152+ million occurrence records ## Authentication Most endpoints are publicly accessible. JWT Bearer tokens are only required for: - Assertion management (add/delete) - User property management Set `ALA_API_KEY` environment variable to use authentication. --- ## Occurrence Search & Data (Public) ### Main Search ``` GET/POST /occurrences/search ``` Search occurrences with faceting support (limited to 5,000 records per request) **Common Parameters:** - `q` (string): Query string (e.g., "Eucalyptus", "*:*" for all) - `fq` (array): Filter queries (e.g., "state:Victoria") - `facets` (string): Facet fields to return - `start` (integer): Pagination offset - `pageSize` (integer): Results per page (default: 10, max: varies) **Spatial Parameters:** - `lat`, `lon`, `radius`: Circle search (radius in km) - `wkt`: Well-Known Text polygon **Example:** ```json { "method": "GET", "endpoint": "/occurrences/search", "params": { "q": "Eucalyptus camaldulensis", "fq": ["state:New South Wales"], "pageSize": 20 } } ``` ### Taxa Count ``` GET/POST /occurrences/taxaCount ``` Report occurrence counts for taxa lists ### Batch Search ``` POST /occurrences/batchSearch ``` Bulk queries for multiple search terms ### Individual Occurrence ``` GET /occurrence/{uuid} ``` Get details for a specific occurrence record **Example:** ```json { "method": "GET", "endpoint": "/occurrence/27339f58-519a-4579-97d2-89de6164fecc" } ``` --- ## Downloads (Public, Email Required) ### Offline Download ``` GET/POST /occurrences/offline/download ``` Asynchronous CSV/TSV export of occurrence data **Required Parameters:** - `email`: Notification email - `reasonTypeId`: Download reason code - `fields`: Comma-separated field list **Optional Parameters:** - `fileType`: "csv" or "tsv" (default: csv) - `dwcHeaders`: Use Darwin Core field names (true/false) - `mintDoi`: Generate DOI for dataset (true/false) - `qa`: Quality assurance filter **Example:** ```json { "method": "POST", "endpoint": "/occurrences/offline/download", "params": { "q": "taxon_name:Eucalyptus", "email": "user@example.com", "reasonTypeId": "10", "fields": "uuid,scientificName,decimalLatitude,decimalLongitude,eventDate", "fileType": "csv" } } ``` ### Facets Download ``` GET/POST /occurrences/facets/download ``` Export complete facet value lists ### Species by Location ``` GET/POST /mapping/species.json ``` Species counts by location --- ## Query Management (Public) ### Create Query ID ``` POST /qid ``` Create cached query ID for complex searches (compresses large payloads) **Purpose:** Convert complex queries into a reusable short identifier ### Retrieve Query ``` GET /qid/{queryID} ``` Retrieve stored query parameters by ID --- ## Assertions & Annotations (Requires Authentication) ### Add Assertion ``` POST /occurrences/{recordUuid}/assertions/add ``` Add data quality assertion to a record **Required Parameters:** - `code`: Assertion type code - `userId`: User identifier - `userDisplayName`: Display name ### Delete Assertion ``` DELETE /occurrences/{recordUuid}/assertions/delete ``` Remove assertion from a record ### Batch Add Assertions ``` POST /occurrences/assertions/add ``` Add assertions to multiple records ### Batch Delete Assertions ``` DELETE /occurrences/assertions/delete ``` Remove assertions from multiple records --- ## User Properties (Requires Authentication) Scopes required: `users/read` or `users/write` ### Get User Property ``` GET /user/property ``` Retrieve user-saved settings **Required Parameters:** - `alaId`: User ALA ID - `name`: Property name ### Set User Property ``` POST /user/property ``` Save user preferences **Required Parameters:** - `alaId`: User ALA ID - `name`: Property name - `value`: Property value --- ## Mapping & Visualization (Public) ### WMS Services ``` GET /mapping/wms/* ``` OGC-compliant Web Map Services for occurrence heat maps ### Charts & Scatterplots Various endpoints for data visualization ### Endemism Reports Species distribution analysis --- ## Data Quality Parameters ### Quality Profiles - `qualityProfile`: Apply predefined data quality standards - Example values: "CSDM", "ALA" ### Filter Controls - `disableAllQualityFilters`: Bypass default validations (true/false) - `disableQualityFilter`: Exclude specific issue categories --- ## Important Constraints - **Search Limit**: Maximum 5,000 records per request - **Large Geometries**: WKT polygons are automatically simplified - **Async Downloads**: Large datasets sent via email - **DOI Generation**: Available with `mintDoi=true` parameter --- ## Common Filter Query (fq) Examples ``` fq=state:Victoria # Filter by state fq=year:[2020 TO 2024] # Date range fq=basis_of_record:HUMAN_OBSERVATION # Observation type fq=taxon_name:Eucalyptus # Taxon filter ``` Multiple filters can be combined: ```json { "fq": [ "state:Victoria", "year:[2020 TO 2024]", "basis_of_record:HUMAN_OBSERVATION" ] } ``` --- ## Facet Fields Common facet fields for aggregations: - `state_conservation` - `basis_of_record` - `taxon_name` - `year` - `month` - `data_resource_uid` - `institution_uid` --- ## Reason Type IDs For downloads, common reason codes: - `0`: Conservation management/planning - `1`: Biosecurity management/planning - `2`: Environmental impact assessment - `3`: Education - `4`: Scientific research - `5`: Collection management - `6`: Other - `7`: Ecological research - `8`: Systematic research - `9`: Citizen science - `10`: Testing - `11`: School education --- ## Additional Resources - **Full API Documentation**: https://docs.ala.org.au/ - **ALA Main Site**: https://www.ala.org.au/ - **Support**: support@ala.org.au