API参考

泰拉数据API参考

面向电网资产、电力市场企业及其从业人员的只读REST API。每条记录均有稳定标识,并注明数据来源。

API 的用途

Tera 是面向电力行业的市场情报平台。业务拓展、投资和研究团队用它了解电站和电网资产由谁持有、建设和运营,某个市场上有哪些活跃的公司,以及在这些公司里该找谁。API 把同样的数据接入您自己的系统:一个熟悉您所在区域每一家开发商的 CRM,一个按您的投资要求筛选电站的模型,或一个在项目易主当天就提醒您的内部工具。

常见任务及对应的调用
您的团队想做什么调用
列出要跟进的项目或电站
梳理某个市场上的活跃公司
找到公司里合适的联系人
交易前核查交易对手
为提案或研究测算市场规模
将 CRM 中的客户匹配到泰拉的公司
列出某企业的资产,及其在每项资产中的角色与份额
关注企业和项目:所有者、状态或项目分期变化时即可获知

基础地址

所有调用均发往泰拉智能数据平台的 /v1 路径,地址如下。响应为JSON格式,仅支持HTTPS。

https://data.teraintel.com/v1

身份验证

将API密钥作为Bearer令牌放入Authorization请求头。切勿将密钥放在查询字符串中,否则API会拒绝该请求。经认证的企业可在数分钟内获得密钥,每月含5,000积分免费额度。

Authorization: Bearer $TERA_API_KEY

每次调用的积分

每次调用从您的额度中扣除积分,响应的meta部分会标明本次消耗。列出记录的调用,每多返回25行加收100积分。验证密钥、查询数据集规模、词表或字段覆盖率均免费。预付密钥查询人员按每位200积分计费,搜索结果与完整记录相同。

响应与错误

调用成功时返回data(记录或结果)和meta(分页与计量信息)。出错时返回ok为false及错误信息。请根据状态码决定后续处理。

错误状态码
状态码含义
400请求格式有误,或筛选值不被接受。错误信息会指明具体原因。
401未提供密钥,或密钥无效。
402本周期的积分额度已用完。
403密钥不具备该调用所需的权限范围,或账户未启用。
404该标识从未由本API发放。
429请求过于频繁。Retry-After响应头会给出需等待的时间。
meta字段
meta.countintegerNumber of records in this page.
meta.credits_chargedintegerCredits this call cost.
meta.credits_usedintegerCredits used this billing period.
meta.credits_includedintegerCredits included in the plan this period.
meta.credits_remainingintegerCredits left for the month (prepaid keys: allowance plus balance).
meta.has_morebooleanWhether another page follows.
meta.limitintegerPage size applied to this response.
meta.offsetintegerRecords skipped before this page.
okbooleanAlways false on an error.
errorstringWhy the request was refused.

关于数据

Read access to Tera's curated dataset.

Identity. Every record carries an opaque id (ast_, org_, per_ prefixed) that is stable across our rebuilds. Store that id, never a name or a URL. If two records are later found to be the same entity they are merged: the id you hold keeps working forever and tells you where it went, so a stored reference never dangles.

Provenance. Records carry the sources behind them. An answer you cannot trace is an answer you should not act on, and every record here can be traced.

Vocabularies are live. Do not hard-code the values a filter accepts. GET /v1/filters returns the current grammar and the real values, free of charge.

A gap in our data is not a gap in the market. Coverage differs from one slice of the market to the next. An empty result means we hold nothing for that query, not that nothing exists; /v1/coverage says how often we hold a field for the slice you are about to quote.

Credits and licences. A prepaid key buys look-ups: a list row finds a record (its operator, estimates, grid capacity and sources come with the full record from /v1/entity), and the change feed, contact details and a person's LinkedIn page are part of a licence. A licence key reads the full row.

接口

GET/v1/assets#

Filtered list of power grid assets

每次调用积分 200, 每多25行加收100积分

What it is for. Building a list of the power plants, substations, EV charging sites and data centres your team targets. A developer sees what is being built in its region, an investor or acquirer finds plants that fit its mandate, an EPC or a manufacturer finds projects heading for construction, an O&M provider finds ageing fleets. Each record names who owns and operates the asset, so a list of assets is also a list of companies to approach. It returns what the Assets list in Tera shows for the same filters.

On a prepaid key a row finds a record: operator, estimates, grid_capacity and sources come with the full record from /v1/entity, at the record's rate, and meta.withheld names them. A licence key reads the full row. Filtering on a value reads it, so a prepaid key may not set grid_available_min or grid_free_bay (it may use has_grid_capacity, grid_direction and grid_technology), and a key that has not topped up may not set est_valuation_min or est_valuation_max; either answers 403. The same holds on /v1/aggregate and /v1/coverage.

Filters accept the values GET /v1/filters reports. Ordering is fixed and deterministic so paging cannot skip or repeat a record.

参数
q可选stringFree-text search. Distinctive words must match; generic industry words (plant, power, solar, farm, ltd) only affect ranking, so "solar farm cork" returns Cork assets rather than nothing. Accent- and case-insensitive, tolerant of typos, and unit numbers are equivalent ("hornsea two" finds "Hornsea 2"). Acronyms resolve on organizations and employers. Results come back in relevance order, which is the same engine and the same ranking the Tera app itself searches with. A query containing nothing distinctive ("solar", "power plant" - only generic industry words) is refused with 400: it matches tens of thousands of records and ranks them all alike, so there is no useful answer to give. Ask those as filters instead (energy_source=solar, kind=power_plant), which is both exact and fast.
limit可选integer (1..)Page size, capped by your plan. See /v1/me.
offset可选integer (0..10000)Capped at 10000. When q is set the cap is 3000 minus your page size, because a relevance search ranks a bounded window and there is no defined order beyond it. Narrow with filters, or use /v1/changes to keep an existing set in sync.
kind可选stringAsset kind: power_plant, substation, charging_station or datacenter. 可选值: power_plantsubstationcharging_stationdatacenter
type可选stringLifecycle status.
country可选stringCountry, by the full name that /v1/filters lists (for example Spain).
energy_class可选stringBroad energy grouping, such as renewable or fossil. Values: /v1/filters.
energy_source可选stringEnergy source, such as solar, wind or natural_gas. Values: /v1/filters.
generation_tech可选stringGeneration technology, such as pv, onshore or ccgt. Values: /v1/filters.
operator可选stringExact match on the operator name shown on the record.
capacity_min可选integerNameplate capacity, kW.
capacity_max可选integerNameplate capacity, kW.
voltage_min可选integerkV.
voltage_max可选integerkV.
year_min可选integerRecords with no commissioning year are always included.
year_max可选integerLatest commissioning year. Records with no commissioning year are always included.
price_min可选numberUSD. Converted before comparison; records we cannot convert drop out.
price_max可选numberHighest reported price, USD. Converted before comparison; records we cannot convert drop out.
address可选stringFree text matched against the street address, locality and postcode.
bbox可选stringmin_lon,min_lat,max_lon,max_lat in WGS84. Rows with no coordinates never match. Prefer near/radius_km unless you genuinely have a rectangle.
near可选stringCentre point as lat,lon - for example near=53.35,-6.26. Requires radius_km, and the two are rejected unless sent together: a default radius would silently answer a different question. True great-circle distance, not a bounding square. Rows with no coordinates never match.
radius_km可选number (0..<501)Radius in km around near, up to 500. Beyond that the search area stops narrowing anything useful - ask it as country= or bbox= instead.
has_picture可选stringSend 1 to keep only assets that have a picture. 可选值: 1
has_name可选stringSend 1 to keep only assets that have a name. 可选值: 1
has_capacity可选stringSend 1 to keep only assets with a nameplate capacity on file. 可选值: 1
has_voltage可选stringSend 1 to keep only assets with a voltage on file. 可选值: 1
has_grid_capacity可选stringSubstations with published grid-access capacity (Spain, Portugal, France, Ireland). 可选值: 1
grid_direction可选stringGrid capacity for connecting generation (default), demand or storage. Any grid_* parameter restricts to substations with a published figure for the question and orders results by it, largest first. 可选值: generationdemandstorage
grid_technology可选stringWhat would connect: any (default), power_park, synchronous, or a word such as solar, wind, battery, gas, hydro. Decides which Spanish transmission figure applies.
grid_available_min可选number (0..)Least capacity a SINGLE connection point must offer, in the publisher's unit (MW; MVA in Portugal and for Irish demand).
grid_free_bay可选stringDrop connection points that publish zero free bays. 可选值: 1

示例

curl "https://data.teraintel.com/v1/assets?country=Spain&energy_source=solar&limit=5" \
  -H "Authorization: Bearer $TERA_API_KEY"
data中每条记录的字段
idstringTera's stable id (ast_, org_, per_). Survives rebuilds and merges.
kindstringAsset kind: power_plant, substation, charging_station or datacenter. 可选值: power_plantsubstationcharging_stationdatacenter
namestringThe name as Tera records it.
statusstringLifecycle status: operating, planned, under_construction, announced, cancelled, retired, mothballed. On the Free plan a project not yet built reads in_development, with no commissioning year.
nameplate_capacityobjectNameplate (rated) capacity, as stored - kW. Not grid capacity, which is grid_capacity.
nameplate_capacity.valueintegerRated output, in the unit beside it.
nameplate_capacity.unitstringUnit of the value: kW unless the record states another.
grid_capacityobjectGrid-access capacity of a substation, present when the publisher of its network releases it: the room left for generation, storage and demand. Null otherwise.
grid_capacity.generationobjectBest connection point for generation: the room it can still take, in the unit stated, with the voltage, the queued request and the free bays.
grid_capacity.generation.availablenumberCapacity the point can still take, for any technology.
grid_capacity.generation.unitstringMW or MVA, as published. MVA is apparent power: real power is at most the MVA figure.
grid_capacity.generation.voltage_kvnumberVoltage of that connection point, kV.
grid_capacity.generation.queuednumberCapacity requested and not yet resolved; it competes for the same room.
grid_capacity.generation.bays_freeintegerFree connection bays (Spain, transmission). 0 means a new connection needs new bays, whatever the MW.
grid_capacity.generation_technologystringWhich technology the generation figure answers: power_park or synchronous. 可选值: power_parksynchronous
grid_capacity.storageobjectBest connection point for storage: the room it can still take, in the unit stated, with the voltage, the queued request and the free bays.
grid_capacity.storage.availablenumberCapacity the point can still take, for any technology.
grid_capacity.storage.unitstringMW or MVA, as published. MVA is apparent power: real power is at most the MVA figure.
grid_capacity.storage.voltage_kvnumberVoltage of that connection point, kV.
grid_capacity.storage.queuednumberCapacity requested and not yet resolved; it competes for the same room.
grid_capacity.storage.bays_freeintegerFree connection bays (Spain, transmission). 0 means a new connection needs new bays, whatever the MW.
grid_capacity.demandobjectBest connection point for demand: the room it can still take, in the unit stated, with the voltage, the queued request and the free bays.
grid_capacity.demand.availablenumberCapacity the point can still take, for any technology.
grid_capacity.demand.unitstringMW or MVA, as published. MVA is apparent power: real power is at most the MVA figure.
grid_capacity.demand.voltage_kvnumberVoltage of that connection point, kV.
grid_capacity.demand.queuednumberCapacity requested and not yet resolved; it competes for the same room.
grid_capacity.demand.bays_freeintegerFree connection bays (Spain, transmission). 0 means a new connection needs new bays, whatever the MW.
grid_capacity.sourcestringThe publisher of the figures behind this summary.
grid_capacity.vintagestringThe publisher's edition the figures come from (e.g. 2026-08, 2026-Q2).
annual_productionobjectEnergy produced in a year (MWh).
annual_production.valuenumberEnergy produced in a year.
annual_production.unitstringAlways MWh.
voltage_kvintegerVoltage in kV (of the asset, or of a connection point).
charging_pointsintegerEV charging: vehicles that can charge at once. Not a power figure.
commissioning_yearintegerYear the asset entered service.
energyobjectThe asset's energy class, energy sources and generation technology.
energy.classstringBroad energy grouping, e.g. renewable or fossil.
energy.sourcesarray of stringThe energy sources the asset uses, such as solar, wind or natural_gas.
energy.generation_techstringGeneration technology, e.g. pv, onshore, ccgt.
locationobjectWhere the asset is: country, locality, address and coordinates.
location.countrystringCountry, by its full name.
location.country_codestringISO 3166-1 alpha-2 country code.
location.localitystringTown or city.
location.postcodestringPostal code.
location.addressstringStreet address.
location.latitudenumberWGS84 latitude.
location.longitudenumberWGS84 longitude.
location.precisionstringsite = the coordinate is the asset. area = it is the area the asset sits in. Absent means we will not claim either, which matters if you are siting anything off these numbers. 可选值: sitearea
operatorstringThe company the record names as operating the asset.
plant_groupstringPresent when this record is one phase of a larger plant.
completenessnumber0 to 1. How much of the record we hold, not a confidence score.
sourcesarray of stringWho the values on this record came from, most-contributing first. Usually a dataset, named as its publisher names it; where we read a value off a published page it is the PUBLISHER of that page - the company whose site described the project, or the body that issued the document - never the name of our own reading process.
updated_atstringWhen the SOURCE last changed, not when our pipeline last ran.
urlstringThe record's page in Tera, for a person to check or share.
  • 200A page of assets.
  • 402Credit allowance for the period is spent.
  • 429Rate limited. Retry-After is set.

GET/v1/organizations#

Filtered list of electricity-market organizations

每次调用积分 200, 每多25行加收100积分

What it is for. Finding the companies active in a market: the developers, utilities, IPPs, EPCs, manufacturers, investors and lenders in a country or a technology. Use it to map competitors, shortlist partners or build a list of prospective clients, then open each company with /v1/entity for its assets, its owners and its people. It returns what the Organizations list in Tera shows. On a prepaid key a row leaves its sources to the full record, and meta.withheld says so.

参数
q可选stringFree-text search. Distinctive words must match; generic industry words (plant, power, solar, farm, ltd) only affect ranking, so "solar farm cork" returns Cork assets rather than nothing. Accent- and case-insensitive, tolerant of typos, and unit numbers are equivalent ("hornsea two" finds "Hornsea 2"). Acronyms resolve on organizations and employers. Results come back in relevance order, which is the same engine and the same ranking the Tera app itself searches with. A query containing nothing distinctive ("solar", "power plant" - only generic industry words) is refused with 400: it matches tens of thousands of records and ranks them all alike, so there is no useful answer to give. Ask those as filters instead (energy_source=solar, kind=power_plant), which is both exact and fast.
limit可选integer (1..)Page size, capped by your plan. See /v1/me.
offset可选integer (0..10000)Capped at 10000. When q is set the cap is 3000 minus your page size, because a relevance search ranks a bounded window and there is no defined order beyond it. Narrow with filters, or use /v1/changes to keep an existing set in sync.
country可选stringCountry, by the full name that /v1/filters lists (for example Spain).
type可选stringCompany role in the market, such as utility, ipp, developer, investor, epc or manufacturer. Values: /v1/filters.
energy_class可选stringBroad energy grouping, such as renewable or fossil. Values: /v1/filters.
energy_source可选stringEnergy source, such as solar, wind or natural_gas. Values: /v1/filters.
generation_tech可选stringGeneration technology, such as pv, onshore or ccgt. Values: /v1/filters.
has_assets可选stringSend 1 to keep only companies linked to at least one asset. 可选值: 1
has_people可选stringSend 1 to keep only companies we hold at least one person for. 可选值: 1
has_ownership可选stringSend 1 to keep only companies with a recorded owner or shareholding. 可选值: 1

示例

curl "https://data.teraintel.com/v1/organizations?country=Spain&type=utility&limit=5" \
  -H "Authorization: Bearer $TERA_API_KEY"
data中每条记录的字段
idstringTera's stable id (ast_, org_, per_). Survives rebuilds and merges.
namestringThe name as Tera records it.
typesarray of stringCompany roles in the market: ipp, utility, investor, developer, epc, manufacturer, ...
locationobjectWhere the company is based: country, locality and the address as a registry states it.
home_pagestringThe company's website.
linkedin_urlstringLinkedIn page.
founded_yearintegerYear founded.
employeesintegerNumber of employees.
financialsobjectRevenue, assets under management and their currency, where we hold them.
energyobjectThe energy classes, sources and technologies of the company's assets.
assetsobjectCounts roll up the ownership subtree where we hold one, which is the figure the Tera app shows for the same company.
assets.countintegerNumber of assets linked to the company.
assets.by_statusobjectThe company's assets counted by lifecycle status (operating, planned, under_construction and so on).
owned_byarray of objectCompanies holding a share of this one.
ownsarray of objectCompanies this one holds a share of.
sourcesarray of stringWho the values on this record came from, most-contributing first. Usually a dataset, named as its publisher names it; where we read a value off a published page it is the PUBLISHER of that page - the company whose site described the project, or the body that issued the document - never the name of our own reading process.
updated_atstringWhen a source last changed this record.
urlstringThe record's page in Tera, for a person to check or share.
  • 200A page of organizations.

GET/v1/organizations/{id}/assets#

A company's assets

每次调用积分 200, 每多25行加收100积分

What it is for. Reading one company's portfolio: the plants, substations and sites it owns, operates, develops or services today, each with its role, its share and since when. A CRM or a credit file fills a company's assets from its id, after /v1/match or /v1/organizations gave it.

Direct links only, as the company's Assets tab in Tera: a subsidiary's assets are on the subsidiary's id (/v1/entity lists a company's subsidiaries), and a link that ended stays on the asset's record. Filter by role and by the asset filters of /v1/assets; ordered by nameplate capacity, largest first. A row is the /v1/assets row, a finder on a prepaid key, and the same filters are refused there. Priced as /v1/assets.

参数
id必填stringA company id from this API (org_...), from /v1/organizations, /v1/match or /v1/entity.
role可选stringKeep the assets on which the company holds one of these roles, a comma list: operator, shareholder, developer, om_provider, epc_contractor, lender, offtaker, ...; only those links are shown.
limit可选integer (1..)Page size, capped by your plan. See /v1/me.
offset可选integer (0..10000)Capped at 10000. When q is set the cap is 3000 minus your page size, because a relevance search ranks a bounded window and there is no defined order beyond it. Narrow with filters, or use /v1/changes to keep an existing set in sync.
kind可选stringAsset kind: power_plant, substation, charging_station or datacenter. 可选值: power_plantsubstationcharging_stationdatacenter
type可选stringLifecycle status.
country可选stringCountry, by the full name that /v1/filters lists (for example Spain).
energy_class可选stringBroad energy grouping, such as renewable or fossil. Values: /v1/filters.
energy_source可选stringEnergy source, such as solar, wind or natural_gas. Values: /v1/filters.
generation_tech可选stringGeneration technology, such as pv, onshore or ccgt. Values: /v1/filters.
operator可选stringExact match on the operator name shown on the record.
capacity_min可选integerNameplate capacity, kW.
capacity_max可选integerNameplate capacity, kW.
voltage_min可选integerkV.
voltage_max可选integerkV.
year_min可选integerRecords with no commissioning year are always included.
year_max可选integerLatest commissioning year. Records with no commissioning year are always included.
price_min可选numberUSD. Converted before comparison; records we cannot convert drop out.
price_max可选numberHighest reported price, USD. Converted before comparison; records we cannot convert drop out.
address可选stringFree text matched against the street address, locality and postcode.
bbox可选stringmin_lon,min_lat,max_lon,max_lat in WGS84. Rows with no coordinates never match. Prefer near/radius_km unless you genuinely have a rectangle.
near可选stringCentre point as lat,lon - for example near=53.35,-6.26. Requires radius_km, and the two are rejected unless sent together: a default radius would silently answer a different question. True great-circle distance, not a bounding square. Rows with no coordinates never match.
radius_km可选number (0..<501)Radius in km around near, up to 500. Beyond that the search area stops narrowing anything useful - ask it as country= or bbox= instead.
has_picture可选stringSend 1 to keep only assets that have a picture. 可选值: 1
has_name可选stringSend 1 to keep only assets that have a name. 可选值: 1
has_capacity可选stringSend 1 to keep only assets with a nameplate capacity on file. 可选值: 1
has_voltage可选stringSend 1 to keep only assets with a voltage on file. 可选值: 1
has_grid_capacity可选stringSubstations with published grid-access capacity (Spain, Portugal, France, Ireland). 可选值: 1
grid_direction可选stringGrid capacity for connecting generation (default), demand or storage. Any grid_* parameter restricts to substations with a published figure for the question and orders results by it, largest first. 可选值: generationdemandstorage
grid_technology可选stringWhat would connect: any (default), power_park, synchronous, or a word such as solar, wind, battery, gas, hydro. Decides which Spanish transmission figure applies.
grid_available_min可选number (0..)Least capacity a SINGLE connection point must offer, in the publisher's unit (MW; MVA in Portugal and for Irish demand).
grid_free_bay可选stringDrop connection points that publish zero free bays. 可选值: 1

示例

curl "https://data.teraintel.com/v1/organizations/org_EXAMPLE/assets?role=shareholder&limit=25" \
  -H "Authorization: Bearer $TERA_API_KEY"
data中每条记录的字段
idstringTera's stable id (ast_, org_, per_). Survives rebuilds and merges.
kindstringAsset kind: power_plant, substation, charging_station or datacenter. 可选值: power_plantsubstationcharging_stationdatacenter
namestringThe name as Tera records it.
statusstringLifecycle status: operating, planned, under_construction, announced, cancelled, retired, mothballed. On the Free plan a project not yet built reads in_development, with no commissioning year.
nameplate_capacityobjectNameplate (rated) capacity, as stored - kW. Not grid capacity, which is grid_capacity.
nameplate_capacity.valueintegerRated output, in the unit beside it.
nameplate_capacity.unitstringUnit of the value: kW unless the record states another.
grid_capacityobjectGrid-access capacity of a substation, present when the publisher of its network releases it: the room left for generation, storage and demand. Null otherwise.
grid_capacity.generationobjectBest connection point for generation: the room it can still take, in the unit stated, with the voltage, the queued request and the free bays.
grid_capacity.generation.availablenumberCapacity the point can still take, for any technology.
grid_capacity.generation.unitstringMW or MVA, as published. MVA is apparent power: real power is at most the MVA figure.
grid_capacity.generation.voltage_kvnumberVoltage of that connection point, kV.
grid_capacity.generation.queuednumberCapacity requested and not yet resolved; it competes for the same room.
grid_capacity.generation.bays_freeintegerFree connection bays (Spain, transmission). 0 means a new connection needs new bays, whatever the MW.
grid_capacity.generation_technologystringWhich technology the generation figure answers: power_park or synchronous. 可选值: power_parksynchronous
grid_capacity.storageobjectBest connection point for storage: the room it can still take, in the unit stated, with the voltage, the queued request and the free bays.
grid_capacity.storage.availablenumberCapacity the point can still take, for any technology.
grid_capacity.storage.unitstringMW or MVA, as published. MVA is apparent power: real power is at most the MVA figure.
grid_capacity.storage.voltage_kvnumberVoltage of that connection point, kV.
grid_capacity.storage.queuednumberCapacity requested and not yet resolved; it competes for the same room.
grid_capacity.storage.bays_freeintegerFree connection bays (Spain, transmission). 0 means a new connection needs new bays, whatever the MW.
grid_capacity.demandobjectBest connection point for demand: the room it can still take, in the unit stated, with the voltage, the queued request and the free bays.
grid_capacity.demand.availablenumberCapacity the point can still take, for any technology.
grid_capacity.demand.unitstringMW or MVA, as published. MVA is apparent power: real power is at most the MVA figure.
grid_capacity.demand.voltage_kvnumberVoltage of that connection point, kV.
grid_capacity.demand.queuednumberCapacity requested and not yet resolved; it competes for the same room.
grid_capacity.demand.bays_freeintegerFree connection bays (Spain, transmission). 0 means a new connection needs new bays, whatever the MW.
grid_capacity.sourcestringThe publisher of the figures behind this summary.
grid_capacity.vintagestringThe publisher's edition the figures come from (e.g. 2026-08, 2026-Q2).
annual_productionobjectEnergy produced in a year (MWh).
annual_production.valuenumberEnergy produced in a year.
annual_production.unitstringAlways MWh.
voltage_kvintegerVoltage in kV (of the asset, or of a connection point).
charging_pointsintegerEV charging: vehicles that can charge at once. Not a power figure.
commissioning_yearintegerYear the asset entered service.
energyobjectThe asset's energy class, energy sources and generation technology.
energy.classstringBroad energy grouping, e.g. renewable or fossil.
energy.sourcesarray of stringThe energy sources the asset uses, such as solar, wind or natural_gas.
energy.generation_techstringGeneration technology, e.g. pv, onshore, ccgt.
locationobjectWhere the asset is: country, locality, address and coordinates.
location.countrystringCountry, by its full name.
location.country_codestringISO 3166-1 alpha-2 country code.
location.localitystringTown or city.
location.postcodestringPostal code.
location.addressstringStreet address.
location.latitudenumberWGS84 latitude.
location.longitudenumberWGS84 longitude.
location.precisionstringsite = the coordinate is the asset. area = it is the area the asset sits in. Absent means we will not claim either, which matters if you are siting anything off these numbers. 可选值: sitearea
operatorstringThe company the record names as operating the asset.
plant_groupstringPresent when this record is one phase of a larger plant.
completenessnumber0 to 1. How much of the record we hold, not a confidence score.
sourcesarray of stringWho the values on this record came from, most-contributing first. Usually a dataset, named as its publisher names it; where we read a value off a published page it is the PUBLISHER of that page - the company whose site described the project, or the body that issued the document - never the name of our own reading process.
updated_atstringWhen the SOURCE last changed, not when our pipeline last ran.
urlstringThe record's page in Tera, for a person to check or share.
linksarray of objectOn /v1/organizations/{id}/assets: the company's current links to this asset, each with its role, share and since when; one asset can carry several (operator and shareholder).
links[].rolestringOn an asset's company, the company's role for this asset: owner, operator, developer, epc, ... On a person, their link to the company they work for: executive, board_member, founder, advisor, or employee (a department head; the people filter seniority=department_head).
links[].sharenumberOwnership share.
links[].sincestringThe date a link began, where a source states it (YYYY-MM-DD).
  • 200A page of the company's assets.
  • 402Credit allowance for the period is spent.
  • 404The id names no company in the current data set.
  • 429Rate limited. Retry-After is set.

POST/v1/match#

Match a company list to Tera ids

每次调用积分 50 (每匹配一家公司计,每次调用至少 50)

What it is for. Mapping the accounts in your CRM or warehouse to Tera's companies, the first step of an enrichment: send your list, store the ids that come back, then open the companies you need with /v1/entity.

Each candidate is tried on its register number, then its website, then its name, and comes back in order with its match, a confidence and what it matched_on. exact: one company carries that register number or website. strong: several companies share the website (a group and its subsidiaries), or the name is the candidate's exactly in its country; the others come back as alternatives. weak: the best name hit, to be checked against the alternatives. none: nothing found, and match is null.

A match is a finder (id, name, country, url): the record is /v1/entity, at its own rate. 50 credits a candidate matched and at least 50 a call; matched candidates count as rows against a prepaid key's month. At most 25 candidates a call on a prepaid key.

请求体
candidatesarray of objectThe companies to match, in the order you want the answers.
candidates[].refstringYour own reference for the candidate (a CRM id), echoed back on its answer.
candidates[].namestringThe company's name as you hold it.
candidates[].countrystringAn ISO 3166-1 alpha-2 code or a country name. Narrows a name match, and lets a bare register number match.
candidates[].websitestringThe company's website, as a URL or a bare domain. Social networks and site builders are ignored.
candidates[].register_idstringThe company's register number, as Tera writes it (GB-COH-01234567) or bare with a two-letter country.

示例

curl "https://data.teraintel.com/v1/match" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"candidates":[{"ref":"crm-1042","name":"Orsted","country":"DK","website":"orsted.com"}]}' \
  -H "Authorization: Bearer $TERA_API_KEY"
data中每条记录的字段
refstringOn /v1/match: the reference the caller sent with the candidate (its own CRM id), echoed back; the candidate's position when none was sent.
matchobjectOn /v1/match: the company the candidate matched, as a finder (id, name, country, url); null when none did. /v1/entity returns the record.
match.idstringTera's stable id (ast_, org_, per_). Survives rebuilds and merges.
match.namestringThe name as Tera records it.
match.countrystringCountry: by full name on /v1 and MCP records; the ISO 3166-1 alpha-2 code on /v1/public/company-lookup items, and in hq, projects and similar on /v1/public/companies.
match.urlstringThe record's page in Tera, for a person to check or share.
confidencestringOn /v1/match: exact (one company carries the register number or website), strong (a shared website, or the exact name in its country) or weak (the best name hit; check the alternatives); none when nothing matched. In estimates: how much of the estimate rests on sourced inputs and a country benchmark, 0 to 1. Lower when a technology, year or geography was assumed, a solar plant's capacity is stated in an unknown basis (AC or DC), or a datacenter is priced on its planned IT load. 可选值: exactstrongweaknone
matched_onarray of stringOn /v1/match: the evidence the match rests on: register_id, website or name. 可选值: register_idwebsitename
alternativesarray of objectOn /v1/match: up to three other companies the candidate could be, as finders, most likely first.
alternatives[].idstringTera's stable id (ast_, org_, per_). Survives rebuilds and merges.
alternatives[].namestringThe name as Tera records it.
alternatives[].countrystringCountry: by full name on /v1 and MCP records; the ISO 3166-1 alpha-2 code on /v1/public/company-lookup items, and in hq, projects and similar on /v1/public/companies.
alternatives[].urlstringThe record's page in Tera, for a person to check or share.
  • 200One answer per candidate, in order.
  • 400The body is not a list of candidates, a candidate has no name, website or register_id, or the list is longer than the key's page.

GET/v1/people#

Electricity-market professionals

每次调用积分 500

What it is for. Finding who to talk to: the leadership and the department heads (grid connections, procurement, origination, asset management and the like) at the companies you target. Go from a company or an asset's owner to a named person here, then call POST /v1/people/{id}/email for their verified work email when you are ready to write. It returns what the People list in Tera shows, with every email hidden until it is revealed.

An empty result means we hold nobody for the query, not that nobody exists; meta.coverage repeats that on every response. On a prepaid key contact.linkedin_available says whether we hold the person's LinkedIn page; the link itself is part of a licence.

参数
q可选stringFree-text search. Distinctive words must match; generic industry words (plant, power, solar, farm, ltd) only affect ranking, so "solar farm cork" returns Cork assets rather than nothing. Accent- and case-insensitive, tolerant of typos, and unit numbers are equivalent ("hornsea two" finds "Hornsea 2"). Acronyms resolve on organizations and employers. Results come back in relevance order, which is the same engine and the same ranking the Tera app itself searches with. A query containing nothing distinctive ("solar", "power plant" - only generic industry words) is refused with 400: it matches tens of thousands of records and ranks them all alike, so there is no useful answer to give. Ask those as filters instead (energy_source=solar, kind=power_plant), which is both exact and fast.
limit可选integer (1..)Page size, capped by your plan. See /v1/me.
offset可选integer (0..10000)Capped at 10000. When q is set the cap is 3000 minus your page size, because a relevance search ranks a bounded window and there is no defined order beyond it. Narrow with filters, or use /v1/changes to keep an existing set in sync.
country可选stringCountry, by the full name that /v1/filters lists (for example Spain).
organization可选stringAn organization id from this API (org_...).
has_email可选stringSend 1 to keep only people we hold a work email for. The address stays hidden until you reveal it (POST /v1/people/{id}/email). 可选值: 1
has_phone可选stringSend 1 to keep only people we hold a phone number for. 可选值: 1
has_picture可选stringSend 1 to keep only people who have a picture. 可选值: 1

示例

curl "https://data.teraintel.com/v1/people?country=Spain&limit=5" \
  -H "Authorization: Bearer $TERA_API_KEY"
data中每条记录的字段
idstringTera's stable id for the person (per_).
namestringThe name as Tera records it.
positionstringJob title.
organizationobjectThe company the person works for: its id, name and page.
contactobjectlinkedin_url (on a licence key; a prepaid key reads linkedin_available instead), plus email_available and phone_available - booleans saying whether we hold a direct contact for this person. The email and phone values themselves are returned only to a key carrying the read:contacts scope, which blanket 'read' does not grant. Without it you learn that a contact exists and can send the user to the entity url; you do not receive the address.
locationobjectWhere the person is based: country and locality.
updated_atstringWhen a source last changed this record.
urlstringThe record's page in Tera, for a person to check or share.
  • 200A page of people.

GET/v1/entity#

Get a full record

每次调用积分 500, 充电站100,含电网接入容量的变电站800

What it is for. Opening one record in full, as its page in Tera does: an asset with its shareholders, developer, operator, offtaker and lenders, or a company with its assets, its owners and its people. Use it to check a counterparty before a deal, to see who stands behind a project, or to refresh a record you store. A prepaid key that has not topped up reads an asset without its estimates and grid_capacity, at the record's base rate, and meta.withheld names them.

Three distinct answers, and a sync that collapses them will delete records it should have kept:

  • 404 we never issued this id.
  • 200 with `meta.state = "absent"` we know the id, the entity is not in the current data set. Keep your record and flag it; you will see a restored event if it returns.
  • 200 with `meta.redirected_from` the id you sent was merged into another entity. Store data[0].id from now on. The old id keeps resolving here indefinitely.
参数
id必填stringThe id to look up: ast_, org_ or per_. An id that was merged resolves to the entity it went into.

示例

curl "https://data.teraintel.com/v1/entity?id=ast_EXAMPLE" \
  -H "Authorization: Bearer $TERA_API_KEY"
  • 200The entity, or an empty data array with meta.state = absent.
  • 404Unknown id.

GET/v1/changes#

What happened to the records you watch

每次调用积分 200, 每多25行加收100积分

What it is for. Knowing when something happens to the companies and assets your team follows: an owner buys or sells a stake, a project moves to construction, a plant is uprated, a new phase is announced. Put the records on a watchlist (/v1/watchlists) and read their events here, then refetch only what moved.

Part of a licence. A prepaid key is refused here and on /v1/watchlists (403). Your licence names how many records the account may watch.

Typed events. status_changed and capacity_changed carry from and to; updated names the other fields that moved in changed_fields; ownership_changed is a company-to-asset link added, ended or re-shared, on both ends, with the role and the shares; phase_added names a new phase of the plant; merged gives the id to keep in redirect_to (the watchlist follows it); removed and restored say a record left the current data set or came back. Each record's events start when it was added to a list.

Pass watchlist to read one list. Store the next_cursor from each response and pass it back as ?since=; every event of one change shares its cursor.

参数
since可选integerCursor from a previous response. Omit for the beginning.
watchlist可选stringRead one of the account's watchlists; without it, every list.
limit可选integer (1..)Page size, capped by your plan. See /v1/me.

示例

curl "https://data.teraintel.com/v1/changes?since=0&watchlist=crm-accounts&limit=100" \
  -H "Authorization: Bearer $TERA_API_KEY"
data中每条记录的字段
cursorintegerPass the last one you processed back as ?since=.
idstringThe id of the entity that changed.
typestringThe kind of record that changed: asset, organization or person. 可选值: assetorganization
eventstringWhat happened: status_changed or capacity_changed (from, to), updated (other fields; changed_fields names them), ownership_changed (a company-to-asset link added, ended or re-shared), phase_added (a new phase joined the plant), merged (redirect_to is the id to keep), removed or restored. 可选值: status_changedcapacity_changedupdatedownership_changedphase_addedmergedremovedrestored
redirect_tostringOn a merge, the id to store from now on.
changed_fieldsarray of stringOn an updated event: the /v1 fields whose value changed (status, location, operator, ...), in the record's order. Absent on a change recorded before Tera kept field-level history.
fromstring or numberThe value before the change: a status, or a nameplate capacity in kW.
tostring or numberThe value after the change: a status, or a nameplate capacity in kW.
actionstringOn ownership_changed: added (a new link), ended (the link is gone) or share_changed (the same link with another share). 可选值: addedendedshare_changed
organizationstringThe company the person works for. On /v1/organizations/{id}/assets: the company whose portfolio this is. On an asset's ownership_changed event: the company the link is to.
assetstringOn a company's ownership_changed event, the asset the link is to; on phase_added, the new phase.
rolestringOn an asset's company, the company's role for this asset: owner, operator, developer, epc, ... On a person, their link to the company they work for: executive, board_member, founder, advisor, or employee (a department head; the people filter seniority=department_head).
share_fromnumberOn ownership_changed: the share before the change, in percent; absent on a new link or one with no stated share.
share_tonumberOn ownership_changed: the share after the change, in percent; absent on an ended link or one with no stated share.
plant_groupstringKey shared by the phases of one multi-phase plant. A grp: or dcc: key names the group by its aggregate asset, with that asset's id in this API (since 2026-10-28; it carried an internal number before).
atstringWhen the change was recorded (ISO 8601).
  • 200A page of changes.
  • 404No watchlist of that name on this account.

GET/v1/watchlists#

Your watchlists

每次调用积分 免费

What it is for. Seeing the lists of companies and assets the account follows, and how many more it may watch (meta.watched_ids of meta.max_watched_ids, the allowance your licence names).

Part of a licence: a prepaid key is refused (403). Managing a list costs no credits; reading its events on /v1/changes does.

该调用无需参数。

示例

curl "https://data.teraintel.com/v1/watchlists" \
  -H "Authorization: Bearer $TERA_API_KEY"
data中每条记录的字段
namestringThe name as Tera records it.
countintegerNumber of records: in a page, a bucket or a portfolio. In a /v1/stats country signal, the plants or companies the signal counts.
created_atstringWhen it was created.
updated_atstringWhen a source last changed this record.
  • 200The account's lists.
  • 403A prepaid key, or a key with no account.

GET/v1/watchlists/{name}#

The records on a watchlist

每次调用积分 免费

What it is for. Reading back a list, paged: each record's id, the id it was watched as when a merge has given it another, and when it was added (its events start there).

Part of a licence: a prepaid key is refused (403). Managing a list costs no credits; reading its events on /v1/changes does.

参数
name必填stringThe list's name: 1 to 48 lowercase letters, digits, - or _.
limit可选integer (1..)Page size, capped by your plan. See /v1/me.
offset可选integer (0..10000)Capped at 10000. When q is set the cap is 3000 minus your page size, because a relevance search ranks a bounded window and there is no defined order beyond it. Narrow with filters, or use /v1/changes to keep an existing set in sync.

示例

curl "https://data.teraintel.com/v1/watchlists/crm-accounts" \
  -H "Authorization: Bearer $TERA_API_KEY"
data中每条记录的字段
idstringTera's stable id (ast_, org_, per_). Survives rebuilds and merges.
watched_asstringThe id the record was put on the list under, when a merge has since given it another (id).
typestringThe kind of record: asset, organization or person; on a search result, what was searched. 可选值: assetorganization
added_atstringWhen the record was put on the list; its events start there.
  • 200A page of the list's records.
  • 404No watchlist of that name.

PUT/v1/watchlists/{name}#

Write a watchlist

每次调用积分 免费

What it is for. Following a set of companies and assets: your CRM accounts, a portfolio, a pipeline. The body is the whole list (it creates the list or replaces it); an id already on it keeps when it was added. Ids from /v1/organizations, /v1/assets, /v1/match or /v1/entity, up to 5,000 a list; an id that names no current company or asset comes back in unknown.

The account's lists together may watch the records its licence names; past that the call is refused (403).

Part of a licence: a prepaid key is refused (403). Managing a list costs no credits; reading its events on /v1/changes does.

参数
name必填stringThe list's name: 1 to 48 lowercase letters, digits, - or _.
请求体
idsarray of stringEvery company and asset id the list should hold.

示例

curl "https://data.teraintel.com/v1/watchlists/crm-accounts" \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{"ids":["org_EXAMPLE","ast_EXAMPLE"]}' \
  -H "Authorization: Bearer $TERA_API_KEY"
data中每条记录的字段
namestringThe name as Tera records it.
countintegerNumber of records: in a page, a bucket or a portfolio. In a /v1/stats country signal, the plants or companies the signal counts.
addedintegerOn a watchlist written: the ids put on it by this call.
removedintegerOn a watchlist written: the ids taken off it by this call.
unknownarray of stringOn a watchlist written: the ids that name no current company or asset; they are not watched.
  • 200The list as written.
  • 400A bad name or body.
  • 403Past the account's allowance, or a prepaid key.

DELETE/v1/watchlists/{name}#

Drop a watchlist

每次调用积分 免费

What it is for. Dropping a list you no longer follow. Its records stop appearing on /v1/changes unless another list holds them.

Part of a licence: a prepaid key is refused (403). Managing a list costs no credits.

参数
name必填stringThe list's name: 1 to 48 lowercase letters, digits, - or _.

示例

curl "https://data.teraintel.com/v1/watchlists/crm-accounts" \
  -X DELETE \
  -H "Authorization: Bearer $TERA_API_KEY"
  • 200The list is gone.
  • 404No watchlist of that name.

GET/v1/filters#

The query grammar and its current values

每次调用积分 免费

What it is for. Learning which countries, technologies, statuses and other values each filter accepts, before you build a query, or a form on top of the API.

Free. Fetch this instead of hard-coding vocabularies: it is generated from the same code that runs the queries, so it cannot drift from what the API accepts.

参数
entity可选stringWhich list to describe: assets, organizations or people. Omit for all three. 可选值: assetsorganizationspeople
kind可选stringFor entity=assets: report the vocabulary for one asset kind.

示例

curl "https://data.teraintel.com/v1/filters?entity=assets" \
  -H "Authorization: Bearer $TERA_API_KEY"
  • 200Filters, values and ranges.

GET/v1/me#

What this key is and what it has spent

每次调用积分 免费

What it is for. Checking that a key works and how much of its allowance is left.

Free. The quickest way to check a key works and to see the limits that apply to it.

该调用无需参数。

示例

curl "https://data.teraintel.com/v1/me" \
  -H "Authorization: Bearer $TERA_API_KEY"
  • 200Scopes, limits and credit usage.

GET/v1/stats#

How much data Tera holds

每次调用积分 免费

What it is for. The size of the dataset at a glance: how many assets, companies and people Tera holds, and in how many countries.

Free. Entity counts for the whole dataset, served from a snapshot rather than computed live (the honest counts take several seconds, which is both slow and a cheap way to make us do expensive work). as_of says when the snapshot was taken.

Two units, each named, never summed. The top-level figures are CURATED ENTITIES: resolved records with source provenance, not raw source rows. reference_geo is a different unit: the feature count of the mapped grid layers (towers, lines, generators, substations and more), which is far larger and describes something else. Each block carries its own unit and note; do not add them together, and do not quote one figure against the other definition.

by_country counts curated entities per ISO 3166-1 alpha-2 country code (substations, operating plants, plants in development, data centres, charging stations, substations with published headroom). Counts only, no capacity totals.

A block that has not been computed on this host answers {"state": "unavailable"} rather than zeroes.

该调用无需参数。

示例

curl "https://data.teraintel.com/v1/stats" \
  -H "Authorization: Bearer $TERA_API_KEY"
  • 200Curated entity counts, reference-geo feature counts and source counts, with the date of the snapshot.

GET/v1/aggregate#

Grouped counts and totals

每次调用积分 300

What it is for. Sizing a market in one call, for a market map, a pitch or a study: the megawatts of solar by country, the largest operators of wind in a country, the plants commissioned each year. Use it where the totals matter more than each record.

Answers how much, so you do not have to page records and add them up. Accepts the same filters as /v1/assets, from the same catalog, so ?country=Spain&energy_source=solar selects exactly the rows the list route would return.

group_by is required and must be one of the dimensions /v1/filters publishes under aggregate.group_by. Buckets are ordered by the largest measure and capped at limit (default 50, max 500), so a high-cardinality dimension like operator gives you the top N rather than every operator.

A null bucket is kept, not dropped. It means the field is not recorded on those rows, and it can be the largest bucket. Dropping it would give you a league table whose leader is an artefact of what we do not hold.

nameplate_capacity_mw omits rows with no capacity on file. Call /v1/coverage for the same slice before quoting a total. A prepaid key that has not topped up reads no valuation total.

q is refused here: an aggregate over a relevance search would total a different set than the one you searched. Express it as filters.

Beyond group_by and entity, this route takes the filters of the entity it totals (/v1/assets or /v1/organizations).

参数
group_by必填stringThe dimension to group by. Required. The dimensions are listed by GET /v1/filters under aggregate.group_by.
entity可选stringWhat to total: assets (the default) or organizations. 可选值: assetsorganizations
limit可选integer (1..)Page size, capped by your plan. See /v1/me.

示例

curl "https://data.teraintel.com/v1/aggregate?group_by=energy_source&country=Spain" \
  -H "Authorization: Bearer $TERA_API_KEY"
  • 200One row per bucket, ordered by the largest measure.
  • 400Unknown or missing group_by, limit out of range, or q supplied.

GET/v1/coverage#

How much of each field we hold, for a slice

每次调用积分 免费

What it is for. Knowing how far to trust a gap. Before a model or a report reads a missing operator or capacity as meaningful, ask how often Tera holds that field for the same slice of the market.

Free. Tells you whether a missing field in a record is unusual. Coverage is measured over a slice: name a country or a kind (assets), a country or a type (organizations), a country or an organization (people). A prepaid key asks 50 coverage questions a UTC day.

A record that omits operator says nothing on its own about whether we normally record one. This route answers that for exactly the rows your filters select, so you can tell we do not hold this from this does not exist - the two readings that collapse into one if you only ever see records.

Coverage varies by slice, which is the point. Quote the figure for the slice you asked about.

Percentages are of matched, the rows these filters select. A low percentage means we do not hold the field for those rows; it is not evidence the fact is absent in the world.

Beyond entity, this route takes the filters of the entity it measures, to describe the slice.

参数
entity可选stringWhich records to measure: assets (the default), organizations or people. 可选值: assetsorganizationspeople

示例

curl "https://data.teraintel.com/v1/coverage?entity=assets&country=Spain" \
  -H "Authorization: Bearer $TERA_API_KEY"
  • 200Matched row count, and recorded count plus percent per field.
  • 400Unknown entity, a rejected filter, or q supplied.

POST/v1/people/{id}/email#

Get a person's verified email

每次调用积分 500

What it is for. Getting a person's work email when your team is ready to contact them, one person at a time.

Needs the read:contacts scope. Every email is hidden until your subscription reveals it; once revealed it also comes back on /people and /entity for every key of the subscription. Counts against the subscription's daily reveal limit; an address revealed before answers again without counting. 500 credits for an address delivered the first time; pending, not_found, not_available and an address revealed before cost nothing. state pending means a lookup is still running: call again.

参数
id必填stringA person id from this API (per_...), from /v1/people or /v1/entity.

示例

curl "https://data.teraintel.com/v1/people/per_EXAMPLE/email" \
  -X POST \
  -H "Authorization: Bearer $TERA_API_KEY"
  • 200The state and, when found, the email and when it was last checked.
  • 429The daily reveal limit is reached.