Global Search

Global search is in alpha. The request and response shapes may still change, and so may the wording of explanations and the list of reason kinds.

Every /v2/search call needs a country. Often you do not have one: a shareholder listed in a foreign filing, a counterparty on an invoice, a holding company whose stated domicile is not where it is incorporated. Or you know the country but not the state: an American company, any of fifty registers. POST /v2/search/global takes what you know in one line of text and returns candidates across every country Topograph covers, or only the countries you choose, best first. Each candidate has the country and registration number you pass to /v2/company, whether it is a strong or a possible match, and a one-sentence explanation of why it matched. When the search can stand behind one of them, that candidate is selected.

Quick example

curl -X POST "https://api.topograph.co/v2/search/global" \
  -H "x-api-key: $TOPOGRAPH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "Bamberger GmbH, Wien" }'

{
  "id": "global-search-1791216000000-k3x9qa",
  "status": "resolved",
  "summary": "Found in Austria: Bamberger GmbH (370916s).",
  "likelyCountryCode": "AT",
  "query": {
    "name": "Bamberger GmbH",
    "legalForm": "GmbH",
    "address": "Wien"
  },
  "candidates": [
    {
      "selected": true,
      "match": "strong",
      "countryCode": "AT",
      "id": "370916s",
      "legalName": "Bamberger GmbH",
      "address": { "city": "Wien", "countryCode": "AT" },
      "isActive": true,
      "explanation": {
        "summary": "The register in Austria lists it under exactly that name; the address you gave points to Austria; the legal form \"GmbH\" is used in Austria.",
        "reasons": [
          { "kind": "register_match", "countryCode": "AT", "text": "The register in Austria lists it under exactly that name" },
          { "kind": "address", "countryCode": "AT", "text": "The address you gave points to Austria" },
          { "kind": "legal_form", "countryCode": "AT", "text": "The legal form \"GmbH\" is used in Austria" }
        ]
      }
    }
  ],
  "usage": { "priceCents": 50, "durationMs": 4180 }
}

The selected candidate is the company, ready for a company request:

curl -X POST "https://api.topograph.co/v2/company" \
  -H "x-api-key: $TOPOGRAPH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "countryCode": "AT", "id": "370916s", "dataPoints": ["company"] }'

Sending what you know

Put everything you know in query, separated by commas. The name comes first; everything after it is read for what it says about the company.

You write	Read as
`Bamberger GmbH, Wien`	address `Wien`
`MFG Investments EOOD, from a UK filing`	the name came from a United Kingdom filing
`Altria Group Inc., Richmond VA, altria.com`	address `Richmond VA`, website `altria.com`
`Metinvest B.V., Netherlands`	a company in the Netherlands
`Acme Holding, HRB 12345`	identifier `HRB 12345`
`96950066U5XAAIRCPA78`	the company this LEI designates
`Приватна компанія Метінвест Б.В. (Metinvest B.V.)`	name with its Latin alias

What was understood comes back in query, so you can check the search read your input as you meant it:

Field	Meaning
`name`	The company name.
`latinName`	Its Latin spelling, when the name is in another script.
`legalForm`	The legal form the name carries.
`address`	The address part.
`identifier`	A registration, VAT or LEI number.
`website`	A website. A national domain is a country signal.
`mentionedCountries`	Countries your text names as where the company is. A belief the search weighs, not a filter.
`sourceCountry`	The country of the filing the name came from. A weak signal: a foreign holder’s stated domicile is often not where it is incorporated.

Add "activeOnly": true to leave out companies the search sees as inactive (an indicative status, see Candidates).

Searching only some countries

countries limits the search to the countries you name. Nothing outside them is searched or returned.

{ "query": "Red Tail Ventures LLC", "countries": ["US"] }

You send	Searched
`["US"]`	Every US state, and nothing else
`["US-DE", "US-NY"]`	Delaware and New York
`["CA"]`	Every Canadian jurisdiction: the federal register (`CA-FED`) and the provinces and territories (`CA-ON`, `CA-QC`, …)
`["DE", "AT", "CH"]`	Germany, Austria and Switzerland

US stands for every state, and CA for every Canadian jurisdiction we cover. When the state is not known, the search looks for it in public sources first, then asks the state registers: the usual incorporation states first (Delaware, New York, Nevada, Wyoming, Florida, Texas), then almost every other state. A Canadian company is returned once, in the jurisdiction it is incorporated in. A federal corporation registered in a province as an extra-provincial corporation is found in both registers; when the two records share a Business Number, or the provincial record names the federal one, the search returns the federal (CA-FED) candidate and lists the provincial registration as an other_registration reason. New Brunswick and Nunavut are not covered yet. countries is a filter. A country named in query is not: it says where you think the company is, and the search can still look elsewhere. When nothing is found in the countries you named and the evidence places the company elsewhere (a GmbH searched in the United States only), the search ends not_found with the reason outside_countries, and likelyCountryCode names the country it points to. The same happens, without any search, for an LEI registered outside them.

Searching by LEI

An LEI names one entity, and the LEI record says where it is registered. Send the LEI alone as query, or next to a name (La Banque Postale, 96950066U5XAAIRCPA78), and the search goes straight to that register: no other country is searched.

{ "query": "96950066U5XAAIRCPA78" }

The candidate carries the reason identifier, “The LEI you gave belongs to a company registered in France”. When the LEI belongs to a company registered in a country Topograph does not cover, the search ends not_found with country_not_covered, and likelyCountryCode names that country.

How it decides

The search works through cheap signals first and stops as soon as one candidate is a strong match.

The name. The legal form and the wording of the name point to the jurisdictions that use them: EOOD is Bulgarian, S.p.A. Italian, GmbH German, Austrian or Swiss. Ltd is most often British, but an American-sounding Ltd is weighed toward the United States. LLC and Inc. point to the United States, and the state still has to be found. Scanning noise such as S.a r.1. is corrected.
The rest of your query, as above: an address, an identifier, a website, a country.
Topograph’s company data, checked once across all countries.
The web, only when the name and Topograph’s data are not enough, or the company is American and its state is unknown. A source page is kept as evidence.
The registers. Live searches in the most likely countries, three at a time, with one rephrased retry when a register returns nothing. The search stops once a register returns the exact name and no other country is a serious contender.

For a US company with no known state, the usual incorporation states are tried first (Delaware, New York, Nevada, Wyoming, Florida, Texas). Then the search moves on through the other states, up to almost every state, six at a time and fastest registers first. When you give an address, it decides a lot. If the address names a country or a US state, that register is asked first, before any web search. When it returns the company under that name at the address you gave, or nearby, the search stops there and no other country is searched. When a register holds several companies with the same name, they are ranked by the distance between their registered address and yours, and each explanation says how far it is (“Its registered address is 3 km from Richmond”). A search runs at most 15 register and web searches, plus up to 40 state registers for a US company with no known state, within 100 seconds.

Reading the answer

status is the first thing to check.

`status`	Meaning	What to do
`resolved`	One strong match, and no plausible rival.	Use the candidate with `selected: true`.
`ambiguous`	Several plausible candidates (the same name exists in Germany and Austria, or twice in one register with nothing to tell them apart), or one candidate that is not strong enough on its own.	Show the candidates to a person, or add what you know to the query and search again.
`not_found`	Nothing acceptable.	Read `reason`.

summary says the same thing in one sentence you can show a user. On not_found, reason says why:

`reason`	Meaning
`not_a_legal_entity`	The input names a class of holders (“Undisclosed shareholders”, “Employees”), a trust or a nominee account. Nothing was searched.
`no_country_signal`	Nothing in the query, Topograph’s data or public sources pointed at a country.
`country_not_covered`	The evidence points to a register Topograph does not cover.
`no_register_match`	The likely countries were searched and none returned the company.
`outside_countries`	You limited the search with `countries`, nothing was found there, and the evidence places the company in another country.
`search_limit_reached`	The search limit was reached before every likely country was tried.
`timeout`	The time limit was reached.

likelyCountryCode names the country the evidence settled on, even when the company could not be confirmed, its register is not covered, or it is outside countries. A Cayman Islands fund still gets its country. id identifies the search. Quote it when you contact support about one.

The company: `selected`

The candidate with selected: true is the one you can use without a person checking it. At most one candidate is selected, always the first, and only when status is resolved. The search selects a candidate only for a strong match with no plausible rival: no candidate of that name in another country, and no other company of the same name in the same register that the evidence cannot tell apart. Two Topograph SAS in France and no address to separate them is ambiguous, not a guess. Take the selected candidate rather than picking from candidates yourself: the decision is the search’s own, made on evidence the response does not all carry.

const result = await response.json();
const company = result.candidates.find((c) => c.selected);
if (company) {
  await getCompany(company.countryCode, company.id);
} else {
  showToReviewer(result.candidates, result.summary);
}

Candidates

Candidates come best first. Each carries countryCode, id, legalName, its registered address and isActive, selected, and a match: strong when the evidence points to this company, possible when it needs a second look. Several candidates can be strong (the same name in Germany and Austria) while none is selected. isActive is indicative only. It is the status the search saw, from a register’s search results or from Topograph’s company data, which can lag the register, so it may be out of date, and it is absent when unknown. activeOnly filters on the same indicative status. Before relying on a company’s status, request company from /v2/company and read company.status. explanation.summary says why it matched in one or two sentences, and explanation.reasons lists the reasons one by one, each with a text you can show as is:

`kind`	Meaning
`register_match`	The register returned the company.
`public_source`	A public page states where it is registered, with its `url`.
`identifier`	The identifier you gave has this country’s format, or the LEI you gave belongs to a company registered there.
`address_match`	The register address matches the address you gave.
`distance`	How far the registered address is from the address you gave.
`address`	The address you gave points to this country.
`legal_form`	The legal form in the name is used in this country.
`source_filing`	The name came from a filing in this country.
`country_hint`	Your query names this country.
`website`	The website domain points to this country.
`company_data`	Topograph’s company data lists it under that name.
`other_registration`	The same company is also registered in another register, under the number given in `text`: a Canadian corporation registered in a province other than its own. When that register publishes neither the home number nor a Business Number, the link rests on the name alone and `text` says a registration with the same name was found. That registration is not listed as a candidate of its own.

Streaming

With "stream": true and the Accept: text/event-stream header, the endpoint sends Server-Sent Events while the search runs:

progress: the search so far, as { revision, activity, candidates, query }. activity lists what the search is doing right now, as sentences you can show (“Asking the register in Austria”); several registers are often asked at once. Its wording is for display and may change. candidates are the ones found so far; none is selected before complete. A new event is sent every time something changes.
complete: the final response, same shape as the non-streaming answer.
error: { error: { code, message } }.

const response = await fetch('https://api.topograph.co/v2/search/global', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.TOPOGRAPH_API_KEY!,
    'Content-Type': 'application/json',
    Accept: 'text/event-stream',
  },
  body: JSON.stringify({ query: 'Altria Group Inc., Richmond VA', stream: true }),
});

const reader = response.body!.pipeThrough(new TextDecoderStream()).getReader();
let buffer = '';
for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  buffer += value;
  const frames = buffer.split('\n\n');
  buffer = frames.pop() ?? '';
  for (const frame of frames) {
    const event = frame.match(/^event: (.*)$/m)?.[1];
    const data = JSON.parse(frame.match(/^data: (.*)$/m)?.[1] ?? '{}');
    if (event === 'progress') console.log(data.activity.join(' · '));
    if (event === 'complete') console.log(data.status, data.summary);
    if (event === 'error') console.error(data.error.code, data.error.message);
  }
}

Streaming is the better choice for anything a person watches: candidates appear as each register answers, and a long search never runs into an HTTP timeout.

Billing

A search is billed only when it succeeds, that is when status is resolved. Ambiguous and not-found searches, inputs rejected as not a legal entity, failures and timeouts are not billed. usage.priceCents shows what the search was charged. The current price is on the pricing page.

Limits and errors

Each account can run 60 global searches per minute and 5 at the same time.

HTTP	`error.code`	Meaning
400	`invalid_request`	`query` is missing or empty, `countries` is empty or holds a code that is not a country, or the request still sends the removed `name` or `hints`.
402	`insufficient_funds`	The account cannot pay for a search.
429	`rate_limited`	Too many searches this minute, or too many running at once. Wait `retryAfterSeconds`.
503	`search_timeout`	The search outlived the request. Use streaming, or add what you know to the query.

Development environments

With an sk_dev_ key, global search answers from generated data: candidates in the countries the name’s legal form points to, each resolvable with /v2/company in the same environment. Coverage is honoured, so a name that only points at uncovered countries ends not_found with country_not_covered, as it would live. A countries filter is honoured too: nothing outside it is generated, and US lands on a state. Nothing is billed.

In the app

The same search is in the app under Global search in the sidebar: one text box, a choice between every country, the United States only or a list of countries, the search progressing live, and the candidates with their explanations. Click a candidate, or Get data, to pick the datapoints and order the company exactly as from the country search.

Getting Started

AI Agents

Integration Guides

Core Features

Behavior & Operations

Quick example

Sending what you know

Searching only some countries

Searching by LEI

How it decides

Reading the answer

The company: `selected`

Candidates

Streaming

Billing

Limits and errors

Development environments

In the app

​Quick example

​Sending what you know

​Searching only some countries

​Searching by LEI

​How it decides

​Reading the answer

​The company: selected

​Candidates

​Streaming

​Billing

​Limits and errors

​Development environments

​In the app

Quick example

Sending what you know

Searching only some countries

Searching by LEI

How it decides

Reading the answer

The company: `selected`

Candidates

Streaming

Billing

Limits and errors

Development environments

In the app