Search Materials Project materials · Routes on Ouro

Route documentation

Learn how to interact with this route using the Ouro SDK or REST API.

API access requires an API key. Create one in Settings → API Keys, then set OURO_API_KEY in your environment.

Request format

Parameters and request body schema for this route.

Request body

limit

integerDefaults to 20

Range: 1 to 100

Maximum number of results to return.

chemsys

Chemical system such as Li-Fe-O or Si-O.

formula

Reduced formula or wildcard formula pattern (e.g. SiO2, ABO3).

sort_by

Optional client-side sort field.

elements

Required elements that must be present.

is_metal

Filter metallic vs non-metallic materials.

is_stable

Filter by thermodynamic stability.

sort_order

stringDefaults to asc

asc

desc

Sort direction when sort_by is provided.

theoretical

Filter theoretical-only entries.

band_gap_max

Maximum band gap in eV.

band_gap_min

Minimum band gap in eV.

material_ids

Specific Materials Project IDs to look up (accepts bare numbers too).

num_sites_max

Maximum number of sites in the structure.

num_sites_min

Minimum number of sites in the structure.

crystal_system

Crystal system filter (triclinic, monoclinic, orthorhombic, tetragonal, trigonal, hexagonal, cubic).

exclude_elements

Elements that must not be present.

spacegroup_number

Space group number.

spacegroup_symbol

Space group Hermann-Mauguin symbol, e.g. P4/mmm.

energy_above_hull_max

Maximum energy above hull in eV/atom.

Retrieve route

Get route metadata including name, visibility, description, and endpoint details. You can retrieve by route ID or identifier.

import os
from ouro import Ouro
 
# Set OURO_API_KEY in your environment or replace os.environ.get("OURO_API_KEY")
ouro = Ouro(api_key=os.environ.get("OURO_API_KEY"))
 
# Option 1: Retrieve by route ID
route_id = "c32019e9-92d8-4c95-ac3a-2e3dd029eb40"
route = ouro.routes.retrieve(route_id)
 
# Option 2: Retrieve by route identifier (username/route-name)
route_identifier = "mmoderwell/search-materials-project-materials"
route = ouro.routes.retrieve(route_identifier)
 
print(route.name, route.visibility)
print(route.metadata)

Use route

Execute the route endpoint with request body, query parameters, or path parameters.

# Retrieve the route
route = ouro.routes.retrieve("mmoderwell/search-materials-project-materials")
 
# Use the route with a request body
response = route.use(
    body={
        'limit': 20,
        'sort_order': 'asc'
    }
)
print(response)

Read actions

Get the request and response history for this route. Actions are especially useful for long-running routes where you can poll the status and retrieve the response when ready.

# Retrieve the route
route = ouro.routes.retrieve("mmoderwell/search-materials-project-materials")
 
# Read all actions (request/response history) for this route
actions = route.read_actions()
print(actions)
 
# Actions are especially useful for long-running routes
# You can poll the status and retrieve the response when ready
for action in actions:
    print(f"Action ID: {action['id']}")
    print(f"Status: {action['status']}")
    print(f"Response: {action.get('response_data')}")

services