{"id":5922,"library":"emmet-api","title":"Emmet API Server","description":"Emmet is a toolkit of packages designed to build the Materials API, which is the Materials Project (MP) specification for defining and disseminating “materials documents”. The `emmet-api` package specifically provides the API server component for serving these material documents. It is currently at version 0.86.3 and receives frequent development builds (e.g., 0.87.0.devX) with stable releases occurring periodically.","status":"active","version":"0.86.3","language":"en","source_language":"en","source_url":"https://github.com/materialsproject/emmet/tree/main/emmet-api/","tags":["API","materials science","materials project","fastapi","server"],"install":[{"cmd":"pip install emmet-api","lang":"bash","label":"Install stable version"},{"cmd":"pip install 'emmet-api[test,docs]' # for optional extras","lang":"bash","label":"Install with optional extras"}],"dependencies":[{"reason":"Requires Python 3.11 or newer.","package":"python","optional":false},{"reason":"Provides core data models and definitions used by the API. While not a direct PyPI dependency of emmet-api, it's fundamental to the Emmet ecosystem.","package":"emmet-core","optional":false}],"imports":[{"note":"emmet-api is built on FastAPI, so many core FastAPI components are imported directly.","symbol":"FastAPI","correct":"from fastapi import FastAPI"},{"note":"This function is used to integrate Emmet's predefined API routes into a FastAPI application.","symbol":"build_router","correct":"from emmet_api.routes import build_router"},{"note":"Used for loading application-specific configurations, such as database connection details.","symbol":"EmmetSettings","correct":"from emmet_api.core.config import EmmetSettings"}],"quickstart":{"code":"import uvicorn\nfrom fastapi import FastAPI\nfrom emmet_api.routes import build_router\nfrom emmet_api.core.config import EmmetSettings\n\n# Initialize FastAPI app\napp = FastAPI(\n    title=\"Emmet API Server Example\",\n    description=\"Minimal Emmet API instance for demonstration\",\n    version=\"0.86.3\"\n)\n\n# Load settings (adjust as per your environment variables or config files)\nsettings = EmmetSettings() # This will load settings from environment variables or .env file\n\n# Build and include routers into the FastAPI app\n# The build_router function modifies the app in-place.\nbuild_router(app, settings)\n\n# To run this application, save it as, e.g., `my_api.py` and execute:\n# uvicorn my_api:app --host 0.0.0.0 --port 8000 --reload\n# Alternatively, if running directly from the installed emmet-api package's entry point:\n# uvicorn emmet_api.main:app --host 0.0.0.0 --port 8000 --reload\n\n# The following lines are for demonstration if this script were the entry point\n# if __name__ == \"__main__\":\n#     uvicorn.run(app, host=\"0.0.0.0\", port=8000)\n\n# Note: This quickstart primarily shows the Python setup. \n# Running the server typically involves the `uvicorn` command-line tool.","lang":"python","description":"The `emmet-api` library primarily provides an API server, built on FastAPI. The quickstart demonstrates how to set up a basic FastAPI application and integrate Emmet's routers. To run the API server, you would typically use the `uvicorn` command, pointing to the configured FastAPI application instance, whether it's a custom script or the default `emmet_api.main:app` entry point provided by the package. Ensure necessary environment variables for `EmmetSettings` (e.g., database connection) are configured."},"warnings":[{"fix":"Refer to the GitHub changelog and release notes for each specific version before upgrading, especially pre-releases. Pin dependencies to exact versions to avoid unexpected breakage.","message":"The Emmet project is under active development with frequent pre-release versions (e.g., `0.87.0.devX`). While `emmet-api` has stable releases, significant architectural and API changes are common across the broader Emmet ecosystem, which may lead to breaking changes in minor versions or impact integration with other Emmet packages.","severity":"breaking","affected_versions":"0.87.0.devX and potentially future minor stable releases"},{"fix":"Familiarize yourself with the `emmet-core` library and install it if you need to work directly with Materials Project data models or schema definitions: `pip install emmet-core`.","message":"While `emmet-api` is a standalone PyPI package, it is part of a larger 'Emmet toolkit' from the Materials Project. Full functionality and understanding of the data models often require interaction with or knowledge of `emmet-core`. Users might need to install `emmet-core` separately to access core document definitions and utilities.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your Python environment is at version 3.11 or newer. Use tools like `pyenv` or `conda` to manage multiple Python versions if needed.","message":"The `emmet-api` package explicitly requires Python >=3.11. Attempting to install or run it with older Python versions will result in installation failures or runtime errors.","severity":"gotcha","affected_versions":"<0.86.3"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}