> ## Documentation Index > Fetch the complete documentation index at: https://docs.gdeltcloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Facilities, minerals and AI compute > Find physical assets, inspect contributing sources and participants, and keep country mineral statistics separate from facility and compute capacity. Use the Facilities directory for physical assets, Natural Resources for country and aggregate mineral statistics, and Epoch for detailed AI compute observations. REST and MCP use the same entity resolution and access controls. The API Arena demonstrates the same REST services. Availability follows the selected, published source release. Check `meta.coverage` for source editions, reference periods, measured geography and participant coverage. An unpublished release returns `503 SOURCE_UNAVAILABLE`; it is not an empty inventory. MCP tools require the matching deployed server contract; a REST release alone does not add tools to an older MCP server. Available archived inputs do not imply a historical-vintage API. ## Where to access the data | Question | REST | MCP category and underlying tool | | - | - | - | | Find a mine, processing plant, factory, port or data center | `GET /api/v2/facilities` | `facilities` → `facilities_search` | | Inspect a physical site | `GET /api/v2/facilities/{facility_id}` | `facilities` → `facilities_get` | | Read contributing source records and capacities | `GET /api/v2/facilities/{facility_id}/observations` | `facilities` → `facilities_observations` | | Inspect physical hierarchy and participants | `GET /api/v2/facilities/{facility_id}/relationships` | `facilities` → `facilities_relationships` | | Read country mineral production or reserves | `GET /api/v2/resources/statistics` | `resources` → `resource_statistics` | | Inspect GPU clusters and chip ownership, use or components | `GET /api/v2/epoch/gpu-clusters`, `/chip-owners`, `/chip-users`, `/chip-components` | `epoch` → `epoch_gpu_clusters`, `epoch_chip_owners`, `epoch_chip_users`, `epoch_chip_components` | | Read other typed Epoch observations | `GET /api/v2/epoch/observations` | `epoch` → `epoch_observations` | | Inspect GEM gas-project finance | `GET /api/v2/energy/finance` | `energy` → `energy_finance` | Facilities and mineral statistics require `can_use_facilities`; detailed Epoch observations require `can_use_epoch_ai`, and GEM finance requires `can_use_gem`. A withheld collection is not evidence of no records. See the [API reference](/reference/endpoints) and [MCP tools](/mcp/tools) for current schemas and access requirements. ## Find U.S. mineral facilities These are request recipes; returned records depend on the published release and your access. Set `GDELT_API_KEY` to your key. Replace the base URL with your local API origin when testing. ```bash theme={null} curl --get 'https://gdeltcloud.com/api/v2/facilities' \ --header "Authorization: Bearer $GDELT_API_KEY" \ --data-urlencode 'source=usgs_domestic' \ --data-urlencode 'country=USA' \ --data-urlencode 'commodity=rare_earths' \ --data-urlencode 'limit=25' ``` The domestic USGS registry supplies U.S. mining and processing facilities. `usgs_myb` supplies international facilities and excludes the United States; that exclusion does not apply to the domestic source or MCS country statistics. Source reference dates are separate from the API release date. The default `granularity=site` returns canonical sites. Use `granularity=unit` for registry units, and copy the returned `facility_id` into detail requests. A mine and its neighboring processing plant remain separate assets unless their physical identity is established. Source files may report a town or state without coordinates: `lat` and `lon` can be null. `has_geo=true` requires both coordinates; inspect `geo_precision` and `geo_evidence` before treating a point as an exact location. ## Read rare-earth reserves without assigning them to mines ```bash theme={null} curl --get 'https://gdeltcloud.com/api/v2/resources/statistics' \ --header "Authorization: Bearer $GDELT_API_KEY" \ --data-urlencode 'source=usgs_mcs' \ --data-urlencode 'country=USA' \ --data-urlencode 'commodity=rare_earths' \ --data-urlencode 'statistic=reserves' \ --data-urlencode 'scope=country' ``` Read the returned reference year, unit, qualifier and native material description together. Rare-earth observations can describe aggregate oxide quantities; they do not establish neodymium or dysprosium production at individual sites. An element price is a different measure from its production. Country reserves are independent statistics, not a sum of listed facility capacities or reserves assigned to those facilities. Diamond series retain natural/synthetic and gem/industrial distinctions in their commodity keys and native descriptions. For example, `commodity=diamond_industrial` selects that normalized series; inspect its unit and native qualifiers before comparing it with `diamond` or other diamond forms. The selected sources do not provide a complete deposit census, water inventories, aquifers, water rights or forest resources. Existing country water indicators are separate context. ## Inspect overlap with GEM Search with `source=gem` or another contributing source. A fused site's `source_memberships` retains every admitted contributing source even when the request filters on one. Follow its `observations_url` to inspect original records and `relationships_url` to inspect participants and physical links. Source units and aliases remain traceable to the canonical site. ```bash theme={null} # Set FACILITY_ID from the previous response; do not substitute an owner entity_id. curl --get "https://gdeltcloud.com/api/v2/facilities/$FACILITY_ID/observations" \ --header "Authorization: Bearer $GDELT_API_KEY" \ --data-urlencode 'limit=25' ``` Compare the source, observation period, capacity unit, material basis and shared-capacity group before calculating anything. Repeated source observations or a multi-commodity shared capacity are not additive totals. Shared ownership and proximity alone do not identify the same physical asset. Ambiguous matches and participants retain their unresolved status. ## Follow a participant through the entity spine Resolve the organization through `GET /api/v2/search?q=Microsoft&type=organization`, inspect the candidates, and select its `entity_id`. Use that returned identifier across endpoints: * `GET /api/v2/facilities?entity={entity_id}` selects recorded ownership. * `GET /api/v2/facilities?participant_entity={entity_id}&participant_role=operator` selects an explicit participant role. * `GET /api/v2/epoch/gpu-clusters?entity={entity_id}&participant_role=owner` selects cluster ownership evidence. A chip designer, foundry, hardware owner, cloud provider, tenant and building owner are different roles. A GPU cluster is a compute observation; it need not identify a physical building. ComputeAtlas fields without cleared provenance are withheld, and coordinates admitted from a separate physical source retain that source's evidence. Deep compute or finance payloads remain behind their own access requirements. For news, use `/api/v2/events?entity={entity_id}` or the site's `/context` endpoint. The latter provides bounded owner/parent reporting with typed relationship paths. It does not establish that the reporting occurred at or affected the facility. Read news date coverage separately from registry editions. `meta.coverage.partial_owner_scope` is true when recorded owners remain unresolved, the owner probe is truncated, or a parent lookup fails. A resolved owner can supply useful news context while other owners remain outside the measured scope. Keep their null entity IDs and names visible rather than treating the context as complete ownership coverage. ## Get a joined reporting view in one request ```http theme={null} GET /api/v2/facilities/{facility_id}/context?days=30&include=nearby&radius_km=25&limit=5 ``` The response combines `facility`, `owner.coverage_paths`, `owner_events` and `owner_stories`. With `include=nearby`, it also returns `nearby_events` and `nearby_stories` for a geographic screen. Recorded parents are considered for each unbridged owner, including when another owner bridges directly. A minority stake does not establish control. Nearby Events are leads around the recorded coordinates, not confirmed incidents at or affecting the site. Read `meta.coverage.reporting` for owner reporting dates and `meta.nearby_coverage.reporting` for nearby reporting dates. `window_complete: false` means some dates remain unavailable. `null` arrays mean a scope could not be measured; empty arrays mean the available reporting was searched without matches. Nearby coverage discloses coordinate precision and uses the requested window; owner reporting can expand an empty short window to 30 days, with the effective window labeled. Facilities Explore starts with **Latest directory updates**, which orders the directory by `last_seen_date`. This is not a news-activity ranking. Expand **Explore owner and nearby reporting** for a bounded preview or open the facility detail for the joined view. The API Arena and API catalog include Facility context. Source observations and participant relationships remain separate drilldowns for detailed provenance. MCP’s `facilities_context` accepts `include=["nearby"]` and `radius_km=25`. The response preserves the REST scopes and coverage metadata. In `owner.coverage_paths`, `relationship_role` distinguishes direct owners, corporate parents and ownership links; an ownership stake does not establish corporate control. `via` identifies the lookup path. ## Make the same requests through MCP Discover the category, inspect the tool schema, then call it. MCP uses typed arrays for Facilities source, country and commodity filters; REST uses comma-separated values. `facility_class` in MCP maps to REST's `class`. ```python theme={null} import asyncio import os from fastmcp import Client from fastmcp.client.auth import BearerAuth async def main(): async with Client( "https://gdelt-cloud-mcp.fastmcp.app/mcp", auth=BearerAuth(token=os.environ["GDELT_API_KEY"]), ) as client: await client.call_tool("facilities_tool_list", {}) await client.call_tool("facilities_tool_get", { "tool_name": "facilities_search", }) facilities = await client.call_tool("facilities_tool_call", { "tool_name": "facilities_search", "tool_arguments": { "source": ["usgs_domestic"], "country": ["USA"], "commodity": ["rare_earths"], "limit": 25, }, }) await client.call_tool("resources_tool_list", {}) await client.call_tool("resources_tool_get", { "tool_name": "resource_statistics", }) reserves = await client.call_tool("resources_tool_call", { "tool_name": "resource_statistics", "tool_arguments": { "source": "usgs_mcs", "country": "USA", "commodity": "rare_earths", "statistic": "reserves", "scope": "country", }, }) print(facilities) print(reserves) asyncio.run(main()) ``` Follow `pagination.next_cursor` with the same filters and check `meta.coverage` on every workflow. MCP discovery does not prove that a collection is published or that your plan can read it. Errors preserve the REST refusal; do not interpret a `403 PLAN_REQUIRED` or `503 SOURCE_UNAVAILABLE` as zero results. For programmatic access, Facilities and Natural Resources return the JSON response as structured content. Categories that also render an interactive view preserve the full API response under `_gdelt.payload`. Read that payload when chaining an entity-search or GEM-finance response into another API call. The [Data & coverage page](https://gdeltcloud.com/data) lists publishers, measured inventories and limitations; the [data catalog](/data/catalog) retains attribution and source-specific rights. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.