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. POST /v2/search/global takes what you know in one line of text and returns ranked candidates across every country Topograph covers. 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.

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" }'

{
  "status": "resolved",
  "summary": "Found in Austria: Bamberger GmbH (370916s).",
  "query": {
    "text": "Bamberger GmbH, Wien",
    "name": "Bamberger GmbH",
    "legalForm": "GmbH",
    "hints": { "address": "Wien" },
    "likelyCountryCode": "AT"
  },
  "candidates": [
    {
      "rank": 1,
      "match": "strong",
      "countryCode": "AT",
      "id": "370916s",
      "legalName": "Bamberger GmbH",
      "address": { "city": "Wien", "countryCode": "AT" },
      "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" }
        ]
      }
    }
  ],
  "countries": [
    { "countryCode": "AT", "outcome": "match", "explanation": "Austria: the register returned the company." },
    { "countryCode": "DE", "outcome": "no_match", "explanation": "Germany: the register returned no company of that name." }
  ],
  "steps": [
    { "index": 0, "kind": "reading_name", "status": "done", "label": "Read your query" },
    { "index": 1, "kind": "company_data", "status": "done", "label": "Checked Topograph's company data" },
    { "index": 2, "kind": "register", "status": "done", "countryCode": "AT", "label": "The register in Austria returned a match" }
  ],
  "usage": { "durationMs": 4180 }
}

The candidate is 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 in query, separated by commas. The name comes first; everything after it is read as a hint.

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

What was understood is returned in query: the name, the legalForm it carries, and the hints read from the text, so you can check the search understood your input. If your data is already structured, send name and hints instead of query:

{
  "name": "Bamberger GmbH",
  "hints": {
    "countries": ["AT", "DE"],
    "excludeCountries": ["GB"],
    "sourceCountry": "IT",
    "address": { "city": "Wien", "countryCode": "AT" },
    "legalForm": "GmbH",
    "identifier": "FN 370916s",
    "website": "bamberger.at"
  }
}

Hint	Meaning
`countries`	Countries you believe in, most likely first. US states as `US-DE`.
`excludeCountries`	Countries already searched without a hit. They are never searched again.
`sourceCountry`	The register the name came from, when it comes from a filing. A foreign holder’s stated domicile is often not where it is incorporated, so this is a weak signal.
`address`	Free text or structured.
`legalForm`	The legal form, when the name does not carry it.
`identifier`	Any registration, VAT or LEI number, in any format.
`website`	A national domain is a country signal.

hints sent with a query take precedence over what was extracted from the text. Add "activeOnly": true to leave out companies the registers report as inactive.

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.
Your hints, as above.
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 in another country.	Use `candidates[0]`.
`ambiguous`	Several plausible candidates (the same name exists in Germany and Austria), or one candidate that is not strong enough on its own.	Show the candidates to a person, or add a hint 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 name, the hints, 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.
`search_limit_reached`	The search limit was reached before every likely country was tried.
`timeout`	The time limit was reached.

query.likelyCountryCode names the country the evidence settled on, even when the company could not be confirmed or its register is not covered. A Cayman Islands fund still gets its country.

Candidates

Each candidate carries countryCode, id, legalName, its registered address and isActive, and a match: strong when the evidence points to this company, possible when it needs a second look. A resolved search has one strong match. 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.
`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`	You named this country.
`website`	The website domain points to this country.
`company_data`	Topograph’s company data lists it under that name.

countries lists the countries considered, each with an outcome (match, no_match, not_searched, not_covered, excluded, unavailable) and a sentence. steps is the search as it ran, one label per step.

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, steps, candidates, countries, query }. A step with status: "running" is in progress, and its label says what it is doing (“Asking the register in Austria”). 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') {
      const running = data.steps.filter((s: any) => s.status === 'running');
      console.log(running.map((s: any) => s.label).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`	Neither `query` nor `name` was sent, or a country code in the hints is not a country.
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 a hint.

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. Nothing is billed.

In the app

The same search is in the app under Global search in the sidebar: one text box, 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

Integration Guides

Core Features

Behavior & Operations

Quick example

Sending what you know

How it decides

Reading the answer

Candidates

Streaming

Billing

Limits and errors

Development environments

In the app

​Quick example

​Sending what you know

​How it decides

​Reading the answer

​Candidates

​Streaming

​Billing

​Limits and errors

​Development environments

​In the app

Quick example

Sending what you know

How it decides

Reading the answer

Candidates

Streaming

Billing

Limits and errors

Development environments

In the app