Facilities, minerals and AI compute

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 and 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.

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

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.

# 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.

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.

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 lists publishers, measured inventories and limitations; the data catalog retains attribution and source-specific rights.

Start here

Monitors

Products

Data

How the data is made

Use cases

Facilities, minerals and AI compute

Where to access the data

Find U.S. mineral facilities

Read rare-earth reserves without assigning them to mines

Inspect overlap with GEM

Follow a participant through the entity spine

Make the same requests through MCP

​Where to access the data

​Find U.S. mineral facilities

​Read rare-earth reserves without assigning them to mines

​Inspect overlap with GEM

​Follow a participant through the entity spine

​Make the same requests through MCP

Where to access the data

Find U.S. mineral facilities

Read rare-earth reserves without assigning them to mines

Inspect overlap with GEM

Follow a participant through the entity spine

Make the same requests through MCP