mineralfyi 0.1.1

Mineral encyclopedia and crystal systems API client — mineralfyi.com

mineralfyi

Python API client and CLI for minerals, crystal systems, and geological classification. Access 6,215 minerals across 10 mineral classes and 7 crystal systems — with chemical formulas, Mohs hardness, specific gravity, luster, streak, cleavage, and fracture data from 198 countries. Zero dependencies.

Extracted from MineralFYI, a mineralogy reference platform with 162 glossary terms, 65 educational guides, and comparison tools for geologists, mineral collectors, educators, and developers building Earth science applications.

Explore minerals at mineralfyi.com — browse the mineral encyclopedia, explore crystal systems, study mineral classes, and read the mineralogy glossary.

Table of Contents

• Install
• Quick Start
• What You Can Do
  • Crystal Systems
  • Mineral Classes
  • Mineral Identification Properties
  • Geographic Distribution
  • Mineral Comparisons
• Command-Line Interface
• MCP Server (Claude, Cursor, Windsurf)
• REST API Client
• API Reference
• Learn More About Minerals
• Also Available
• Science FYI Family
• FYIPedia Developer Tools
• License

Install

pip install mineralfyi                # Core (zero deps)
pip install "mineralfyi[cli]"         # + Command-line interface (typer, rich)
pip install "mineralfyi[mcp]"         # + MCP server for AI assistants
pip install "mineralfyi[api]"         # + HTTP client for mineralfyi.com API
pip install "mineralfyi[all]"         # Everything

Or run instantly without installing:

uvx --from mineralfyi mineralfyi search quartz

Quick Start

from mineralfyi.api import MineralFYI

with MineralFYI() as api:
    # Look up any mineral — 6,215 minerals in the database
    quartz = api.get_mineral("quartz")
    print(quartz["name"])             # Quartz
    print(quartz["formula"])          # SiO2
    print(quartz["hardness"])         # 7.0
    print(quartz["crystal_system"])   # trigonal
    print(quartz["luster"])           # vitreous
    print(quartz["streak"])           # White
    print(quartz["cleavage"])         # None
    print(quartz["fracture"])         # Conchoidal

    # Browse crystal systems and mineral classes
    crystal_systems = api.list_crystal_systems()
    classes = api.list_classes()

What You Can Do

Crystal Systems

All crystalline minerals form in one of 7 crystal systems, defined by the symmetry of their unit cell — the smallest repeating unit of the crystal lattice. Crystal system is the most fundamental classification in mineralogy, determining optical properties, cleavage planes, and crystal habit.

Crystal System	Axes	Angles	Mineral Count	Examples
Cubic (Isometric)	a = b = c	All 90 degrees	—	Diamond, Pyrite, Halite, Garnet, Galena
Hexagonal	a1 = a2 = a3, c	120 degrees / 90 degrees	—	Beryl, Apatite, Graphite, Molybdenite
Trigonal	a1 = a2 = a3, c	120 degrees / 90 degrees	—	Quartz, Calcite, Corundum, Tourmaline, Hematite
Tetragonal	a = b, c	All 90 degrees	—	Zircon, Rutile, Cassiterite, Wulfenite
Orthorhombic	a, b, c all different	All 90 degrees	—	Topaz, Olivine, Barite, Aragonite, Sulfur
Monoclinic	a, b, c all different	Two 90 degrees, one oblique	—	Gypsum, Orthoclase, Augite, Epidote
Triclinic	a, b, c all different	No right angles	—	Plagioclase, Kyanite, Turquoise, Rhodonite

The cubic system has the highest symmetry (48 symmetry elements), while triclinic has the lowest (2 elements). Most rock-forming minerals crystallize in the monoclinic, orthorhombic, or trigonal systems.

from mineralfyi.api import MineralFYI

with MineralFYI() as api:
    # List all 7 crystal systems
    systems = api.list_crystal_systems()
    for s in systems["results"]:
        print(s["slug"], s["name"])
        # cubic, Cubic (Isometric)
        # hexagonal, Hexagonal
        # monoclinic, Monoclinic
        # orthorhombic, Orthorhombic
        # tetragonal, Tetragonal
        # triclinic, Triclinic
        # trigonal, Trigonal

    # Get crystal system detail
    cubic = api.get_crystal_system("cubic")
    print(cubic)

Learn more: Crystal Systems · Mineralogy Glossary · Mineral Guides

Mineral Classes

Minerals are grouped into 10 chemical classes based on their dominant anion or anionic group. The Dana classification system (first published 1837, now in its 8th edition) is the standard used by MineralFYI.

Class	Description	Notable Minerals
Native Elements	Uncombined elements	Gold, Silver, Copper, Diamond, Sulfur
Sulfides & Sulfosalts	Metal-sulfur bonds	Pyrite, Galena, Chalcopyrite, Sphalerite
Halides	Metal-halogen bonds	Halite (NaCl), Fluorite (CaF2)
Oxides & Hydroxides	Metal-oxygen bonds	Hematite, Magnetite, Corundum, Goethite
Carbonates & Nitrates	CO3 or NO3 groups	Calcite, Dolomite, Malachite, Azurite
Borates	BO3 or BO4 groups	Borax, Ulexite, Colemanite
Sulfates, Chromates, Molybdates	SO4, CrO4, MoO4 groups	Gypsum, Barite, Celestine, Wulfenite
Phosphates, Arsenates, Vanadates	PO4, AsO4, VO4 groups	Apatite, Turquoise, Vanadinite
Silicates	SiO4 tetrahedra	Quartz, Feldspar, Mica, Olivine, Garnet
Organic Minerals	Carbon-based compounds	Whewellite, Mellite, Amber (borderline)

Silicates are by far the most abundant class, making up approximately 90% of the Earth's crust. They are further subdivided by SiO4 tetrahedra arrangement: nesosilicates (isolated), sorosilicates (pairs), cyclosilicates (rings), inosilicates (chains), phyllosilicates (sheets), and tectosilicates (frameworks).

from mineralfyi.api import MineralFYI

with MineralFYI() as api:
    # List all 10 mineral classes
    classes = api.list_classes()
    for c in classes["results"]:
        print(c["slug"], c["name"])

    # Get class detail with member minerals
    silicates = api.get_classe("silicates")
    print(silicates)

Learn more: Mineral Classes · Mineralogy Glossary

Mineral Identification Properties

Every mineral in the database includes the physical and optical properties used in standard geological identification. These are the properties a geologist tests in the field and laboratory.

Property	What It Measures	Example (Quartz)
Chemical Formula	Composition	SiO2
Mohs Hardness	Scratch resistance (1-10)	7.0
Specific Gravity	Density relative to water	2.65
Crystal System	Lattice symmetry	Trigonal
Luster	Surface light reflection	Vitreous
Streak	Powder color on porcelain	White
Cleavage	Preferred breaking planes	None
Fracture	Breaking pattern (non-cleavage)	Conchoidal
Transparency	Light transmission	Transparent
Crystal Habit	Typical growth form	Prismatic, massive, druzy
Color	Visual appearance	Colorless, white, purple, pink, brown, black

The Mohs hardness scale (developed by Friedrich Mohs in 1812) ranks minerals from 1 (talc) to 10 (diamond). It is a relative scale — diamond (10) is roughly 4 times harder than corundum (9), while the jump from talc (1) to gypsum (2) is small. A steel knife has hardness ~5.5, a copper coin ~3.5, and a fingernail ~2.5.

from mineralfyi.api import MineralFYI

with MineralFYI() as api:
    # Look up quartz — second most abundant crustal mineral
    quartz = api.get_mineral("quartz")
    print(quartz["formula"])          # SiO2
    print(quartz["hardness"])         # 7.0
    print(quartz["specific_gravity"]) # 2.65
    print(quartz["crystal_system"])   # trigonal
    print(quartz["luster"])           # vitreous
    print(quartz["streak"])           # White
    print(quartz["cleavage"])         # None
    print(quartz["fracture"])         # Conchoidal
    print(quartz["transparency"])     # transparent
    print(quartz["crystal_habit"])    # Prismatic, massive, druzy

Learn more: Mineral Encyclopedia · Mineral Guides

Geographic Distribution

MineralFYI tracks mineral occurrences across 198 countries, connecting minerals to their type localities and notable collection sites. Geographic provenance is important for both scientific classification (type locality defines the mineral species) and collector value.

from mineralfyi.api import MineralFYI

with MineralFYI() as api:
    # Browse 198 countries with mineral occurrences
    countries = api.list_countries()
    print(countries["count"])  # 198

    # Get country detail with associated minerals
    detail = api.get_country("brazil")

Learn more: Countries · Mineral Guides

Mineral Comparisons

Compare two minerals side-by-side across all identification properties. Pre-computed comparisons highlight differences in hardness, crystal system, luster, and chemical composition for commonly confused mineral pairs (e.g., quartz vs. calcite, pyrite vs. gold).

from mineralfyi.api import MineralFYI

with MineralFYI() as api:
    # Browse mineral comparisons
    comparisons = api.list_comparisons(limit=5)
    for comp in comparisons["results"]:
        print(comp["slug"])

Learn more: Mineral Comparisons · Mineralogy Glossary

Command-Line Interface

pip install "mineralfyi[cli]"

mineralfyi search quartz             # Search minerals by name
mineralfyi search "iron oxide"       # Search by composition
mineralfyi search fluorite           # Search by mineral name

MCP Server (Claude, Cursor, Windsurf)

Add mineral lookup tools to any AI assistant that supports Model Context Protocol.

pip install "mineralfyi[mcp]"

Add to your claude_desktop_config.json:

{
    "mcpServers": {
        "mineralfyi": {
            "command": "uvx",
            "args": ["--from", "mineralfyi[mcp]", "python", "-m", "mineralfyi.mcp_server"]
        }
    }
}

REST API Client

pip install "mineralfyi[api]"

from mineralfyi.api import MineralFYI

with MineralFYI() as api:
    minerals = api.list_minerals()                 # GET /api/v1/minerals/
    quartz = api.get_mineral("quartz")             # GET /api/v1/minerals/quartz/
    systems = api.list_crystal_systems()           # GET /api/v1/crystal-systems/
    classes = api.list_classes()                    # GET /api/v1/classes/
    countries = api.list_countries()                # GET /api/v1/countries/
    results = api.search("feldspar")               # GET /api/v1/search/?q=feldspar

Example

curl -s "https://mineralfyi.com/api/v1/minerals/quartz/"

{
  "name": "Quartz",
  "slug": "quartz",
  "formula": "SiO2",
  "crystal_system": "trigonal",
  "mineral_class": "silicates",
  "hardness": "7.0",
  "specific_gravity": "2.65",
  "color": "Colorless, white, purple, pink, brown, black",
  "luster": "vitreous",
  "streak": "White",
  "cleavage": "None",
  "fracture": "Conchoidal",
  "transparency": "transparent"
}

Full API documentation at mineralfyi.com/developers/.

API Reference

Method	Description
list_minerals(**params)	List all 6,215 minerals with pagination
get_mineral(slug)	Get mineral detail with full identification properties
list_crystal_systems(**params)	List all 7 crystal systems
get_crystal_system(slug)	Get crystal system detail
list_classes(**params)	List all 10 mineral classes
get_classe(slug)	Get mineral class detail with member minerals
list_countries(**params)	List 198 countries with mineral occurrences
get_country(slug)	Get country detail
list_comparisons(**params)	List mineral comparisons
get_comparison(slug)	Get side-by-side comparison
list_glossary(**params)	List 162 mineralogy glossary terms
get_term(slug)	Get glossary term definition
list_guides(**params)	List 65 educational guides
get_guide(slug)	Get guide content
search(query)	Search across all mineral content

Learn More About Minerals

• Browse: Mineral Encyclopedia · Crystal Systems · Mineral Classes · Countries
• Compare: Mineral Comparisons
• Reference: Mineralogy Glossary
• Guides: Educational Guides
• API: REST API Docs · OpenAPI Spec

Also Available

Platform	Install	Link
npm	npm install mineralfyi	npm
MCP	uvx --from "mineralfyi[mcp]" python -m mineralfyi.mcp_server	Config

Science FYI Family

Part of the FYIPedia open-source developer tools ecosystem — physical sciences, chemistry, geology, astronomy, and materials.

Package	PyPI	npm	Description
chemfyi	PyPI	npm	Periodic table, 500 compounds, 371 reactions — chemfyi.com
alloyfyi	PyPI	npm	765 metal alloys, 12 families, compositions — alloyfyi.com
gemfyi	PyPI	npm	442 gemstones, Mohs scale, grading — gemfyi.com
starfyi	PyPI	npm	119,602 stars, 6,128 exoplanets, 13,305 deep-sky objects — starfyi.com
mineralfyi	PyPI	npm	6,215 minerals, 7 crystal systems — mineralfyi.com

FYIPedia Developer Tools

Package	PyPI	npm	Description
colorfyi	PyPI	npm	Color conversion, WCAG contrast, harmonies — colorfyi.com
emojifyi	PyPI	npm	Emoji encoding & metadata for 3,953 emojis — emojifyi.com
symbolfyi	PyPI	npm	Symbol encoding in 11 formats — symbolfyi.com
unicodefyi	PyPI	npm	Unicode lookup with 17 encodings — unicodefyi.com
fontfyi	PyPI	npm	Google Fonts metadata & CSS — fontfyi.com
distancefyi	PyPI	npm	Haversine distance & travel times — distancefyi.com
timefyi	PyPI	npm	Timezone ops & business hours — timefyi.com
namefyi	PyPI	npm	Korean romanization & Five Elements — namefyi.com
unitfyi	PyPI	npm	Unit conversion, 220 units — unitfyi.com
holidayfyi	PyPI	npm	Holiday dates & Easter calculation — holidayfyi.com
cocktailfyi	PyPI	—	Cocktail ABV, calories, flavor — cocktailfyi.com
fyipedia	PyPI	—	Unified CLI: fyi mineral info quartz — fyipedia.com
fyipedia-mcp	PyPI	—	Unified MCP hub for AI assistants — fyipedia.com

License

MIT