Crate mindat_rs 

mindat-rs

A Rust client library for the Mindat API.

Mindat is the world’s largest open database of minerals, rocks, meteorites, and the localities where they come from. This crate provides a type-safe, async interface to access mineralogical data.

Features

• Full coverage of the Mindat API endpoints
• Strongly-typed request builders and response models
• Async/await support using tokio
• Pagination helpers
• Comprehensive error handling

Quick Start

use mindat_rs::{MindatClient, GeomaterialsQuery, Result};

#[tokio::main]
async fn main() -> Result<()> {
    // Create a client with your API token
    let client = MindatClient::new("your-api-token");

    // Search for quartz
    let query = GeomaterialsQuery::new()
        .name("quartz")
        .ima_approved(true);

    let minerals = client.geomaterials(query).await?;

    for mineral in minerals.results {
        println!("{}: {:?}", mineral.id, mineral.name);
    }

    Ok(())
}

Authentication

Most API endpoints require authentication with a Mindat API token. You can obtain a token from your Mindat account settings.

Some endpoints (like minerals_ima) can be accessed without authentication:

use mindat_rs::{MindatClient, ImaMineralsQuery};

let client = MindatClient::anonymous();
let minerals = client.minerals_ima(ImaMineralsQuery::new()).await?;

Pagination

Most list endpoints return paginated results. Use the pagination helpers:

use mindat_rs::{MindatClient, GeomaterialsQuery};

let client = MindatClient::new("token");

// Get first page
let query = GeomaterialsQuery::new().page(1).page_size(100);
let page1 = client.geomaterials(query).await?;

// Check if there are more pages
if page1.has_next() {
    let query = GeomaterialsQuery::new().page(2).page_size(100);
    let page2 = client.geomaterials(query).await?;
}

Available Endpoints

• Geomaterials: Search minerals, rocks, varieties, synonyms, and more
• Localities: Search mineral localities worldwide (+ name translations)
• IMA Minerals: Full search over IMA-approved mineral species (no API key required)
• References: Bibliographic references, authors, citations, and lookup tables
• Occurrences: Mineral-at-locality occurrences and aggregated statistics
• Crystallography: Crystal classes, space groups, and space-group sets
• Relations: Relationships between minerals
• Geospatial: Point/polygon queries for localities and mineral occurrences
• Classification: Dana 8th ed. and Nickel-Strunz 10th ed. systems
• Locality Metadata: Ages, statuses, and types
• Exports: Bulk data export links

Note on the Mindat API (v1)

The standalone /countries/, /photocount/, and /locgeoregion2/ endpoints were removed upstream and are no longer part of this crate. Filter localities by country using LocalitiesQuery::country (e.g. "USA", "Brazil"). Note also that /geomaterials/ and /minerals-ima/ use the el_inc/el_exc element filters and page-size, while /localities/ keeps elements_inc/ elements_exc; the builders hide these differences.

Re-exports

pub use client::DEFAULT_BASE_URL;

pub use client::MindatClient;

pub use client::MindatClientBuilder;

pub use error::MindatError;

pub use error::Result;

pub use models::*;

Modules

client

HTTP client for the Mindat API.

error

Error types for the Mindat API client.

models

Data models for the Mindat API.