Find a company across countries from its name
curl --request POST \
--url https://api.topograph.co/v2/search/global \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"query": "Bamberger GmbH, Wien",
"name": "Bamberger GmbH",
"hints": {
"countries": [
"DE",
"AT"
],
"excludeCountries": [
"GB"
],
"sourceCountry": "IT",
"address": "Via Roma 1, 20121 Milano, Italia",
"legalForm": "GmbH",
"identifier": "DE812345678",
"website": "https://example.fr"
},
"activeOnly": false,
"stream": false
}
'import requests
url = "https://api.topograph.co/v2/search/global"
payload = {
"query": "Bamberger GmbH, Wien",
"name": "Bamberger GmbH",
"hints": {
"countries": ["DE", "AT"],
"excludeCountries": ["GB"],
"sourceCountry": "IT",
"address": "Via Roma 1, 20121 Milano, Italia",
"legalForm": "GmbH",
"identifier": "DE812345678",
"website": "https://example.fr"
},
"activeOnly": False,
"stream": False
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: 'Bamberger GmbH, Wien',
name: 'Bamberger GmbH',
hints: {
countries: ['DE', 'AT'],
excludeCountries: ['GB'],
sourceCountry: 'IT',
address: 'Via Roma 1, 20121 Milano, Italia',
legalForm: 'GmbH',
identifier: 'DE812345678',
website: 'https://example.fr'
},
activeOnly: false,
stream: false
})
};
fetch('https://api.topograph.co/v2/search/global', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.topograph.co/v2/search/global",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => 'Bamberger GmbH, Wien',
'name' => 'Bamberger GmbH',
'hints' => [
'countries' => [
'DE',
'AT'
],
'excludeCountries' => [
'GB'
],
'sourceCountry' => 'IT',
'address' => 'Via Roma 1, 20121 Milano, Italia',
'legalForm' => 'GmbH',
'identifier' => 'DE812345678',
'website' => 'https://example.fr'
],
'activeOnly' => false,
'stream' => false
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.topograph.co/v2/search/global"
payload := strings.NewReader("{\n \"query\": \"Bamberger GmbH, Wien\",\n \"name\": \"Bamberger GmbH\",\n \"hints\": {\n \"countries\": [\n \"DE\",\n \"AT\"\n ],\n \"excludeCountries\": [\n \"GB\"\n ],\n \"sourceCountry\": \"IT\",\n \"address\": \"Via Roma 1, 20121 Milano, Italia\",\n \"legalForm\": \"GmbH\",\n \"identifier\": \"DE812345678\",\n \"website\": \"https://example.fr\"\n },\n \"activeOnly\": false,\n \"stream\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.topograph.co/v2/search/global")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"Bamberger GmbH, Wien\",\n \"name\": \"Bamberger GmbH\",\n \"hints\": {\n \"countries\": [\n \"DE\",\n \"AT\"\n ],\n \"excludeCountries\": [\n \"GB\"\n ],\n \"sourceCountry\": \"IT\",\n \"address\": \"Via Roma 1, 20121 Milano, Italia\",\n \"legalForm\": \"GmbH\",\n \"identifier\": \"DE812345678\",\n \"website\": \"https://example.fr\"\n },\n \"activeOnly\": false,\n \"stream\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.topograph.co/v2/search/global")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"Bamberger GmbH, Wien\",\n \"name\": \"Bamberger GmbH\",\n \"hints\": {\n \"countries\": [\n \"DE\",\n \"AT\"\n ],\n \"excludeCountries\": [\n \"GB\"\n ],\n \"sourceCountry\": \"IT\",\n \"address\": \"Via Roma 1, 20121 Milano, Italia\",\n \"legalForm\": \"GmbH\",\n \"identifier\": \"DE812345678\",\n \"website\": \"https://example.fr\"\n },\n \"activeOnly\": false,\n \"stream\": false\n}"
response = http.request(request)
puts response.read_body{
"status": "resolved",
"summary": "Found in Austria: Bamberger GmbH (370916s).",
"query": {
"text": "Bamberger GmbH, Wien",
"name": "Bamberger GmbH",
"hints": {
"countries": [
"DE",
"AT"
],
"excludeCountries": [
"GB"
],
"sourceCountry": "IT",
"address": "Via Roma 1, 20121 Milano, Italia",
"legalForm": "GmbH",
"identifier": "DE812345678",
"website": "https://example.fr"
},
"latinName": "<string>",
"legalForm": "GmbH",
"likelyCountryCode": "KY"
},
"candidates": [
{
"rank": 123,
"match": "strong",
"countryCode": "AT",
"id": "370916s",
"legalName": "Bamberger GmbH",
"explanation": {
"summary": "<string>",
"reasons": [
{
"kind": "legal_form",
"text": "The register in Austria lists it under exactly that name",
"countryCode": "AT",
"url": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000764180"
}
]
},
"legalNameInEnglish": "<string>",
"companyNameTransliterations": [
"<string>"
],
"address": {
"addressLine1": "10 rue de la Fraternité",
"addressLine2": "Topograph Building",
"city": "Bagnolet",
"postalCode": "93170",
"region": "FR",
"countryCode": "FR",
"poBox": "PO Box 123",
"careOf": "c/o John Doe",
"state": "Île-de-France",
"latitude": 59.9139,
"longitude": 10.7522
},
"isActive": true
}
],
"countries": [
{
"countryCode": "DE",
"outcome": "match",
"explanation": "Germany: the register returned no company of that name."
}
],
"steps": [
{
"index": 123,
"kind": "reading_name",
"status": "running",
"label": "Asking the register in Austria",
"countryCode": "<string>"
}
],
"usage": {
"priceCents": 123,
"durationMs": 123
},
"reason": "not_a_legal_entity"
}{
"statusCode": 400,
"error": {
"code": "invalid_request",
"message": "name is required and cannot be empty"
}
}{
"statusCode": 402,
"error": {
"code": "insufficient_funds",
"message": "Not enough credits for a global search."
}
}{
"statusCode": 429,
"error": {
"code": "rate_limited",
"message": "Too many global searches this minute for this account. Retry shortly."
}
}{
"statusCode": 503,
"error": {
"code": "search_timeout",
"message": "The global search took too long to complete."
}
}Search
Find a company across countries from its name
Takes what you know about a company in one free-text query (the name plus a city, a country, a registration number, a website…), or a name with structured hints, and returns ranked candidates across the countries Topograph covers, each with a registration number you can pass to /v2/company, a confidence and an explanation of the evidence.
The search is agentic and bounded: it reads the legal form and any address, checks Topograph’s index, asks the web when the name and that data are not enough, confirms in the most likely registers (US states included), and stops as soon as one candidate is a strong match. At most 15 live and web searches, at most 100 seconds.
Status. resolved: one strong match. ambiguous: several plausible candidates (the same name in two countries, a US company whose state is not established), all returned with their evidence. not_found: nothing acceptable; reason says why, and query.discoveredCountryCode names the country the evidence pointed to even when Topograph does not cover it.
Alpha. The request and response shapes may still change.
Billing. A search is billed only when it succeeds: status: resolved, one good candidate. Ambiguous and not-found searches, inputs rejected as not a legal entity, failures and timeouts are not billed. usage.priceCents shows what was charged; the price is on the pricing page.
Streaming. With stream: true and Accept: text/event-stream, the endpoint emits progress events (the plan so far: steps, country assessments, candidates), then one complete event with the final response, or an error event.
POST
/
v2
/
search
/
global
Find a company across countries from its name
curl --request POST \
--url https://api.topograph.co/v2/search/global \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"query": "Bamberger GmbH, Wien",
"name": "Bamberger GmbH",
"hints": {
"countries": [
"DE",
"AT"
],
"excludeCountries": [
"GB"
],
"sourceCountry": "IT",
"address": "Via Roma 1, 20121 Milano, Italia",
"legalForm": "GmbH",
"identifier": "DE812345678",
"website": "https://example.fr"
},
"activeOnly": false,
"stream": false
}
'import requests
url = "https://api.topograph.co/v2/search/global"
payload = {
"query": "Bamberger GmbH, Wien",
"name": "Bamberger GmbH",
"hints": {
"countries": ["DE", "AT"],
"excludeCountries": ["GB"],
"sourceCountry": "IT",
"address": "Via Roma 1, 20121 Milano, Italia",
"legalForm": "GmbH",
"identifier": "DE812345678",
"website": "https://example.fr"
},
"activeOnly": False,
"stream": False
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: 'Bamberger GmbH, Wien',
name: 'Bamberger GmbH',
hints: {
countries: ['DE', 'AT'],
excludeCountries: ['GB'],
sourceCountry: 'IT',
address: 'Via Roma 1, 20121 Milano, Italia',
legalForm: 'GmbH',
identifier: 'DE812345678',
website: 'https://example.fr'
},
activeOnly: false,
stream: false
})
};
fetch('https://api.topograph.co/v2/search/global', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.topograph.co/v2/search/global",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => 'Bamberger GmbH, Wien',
'name' => 'Bamberger GmbH',
'hints' => [
'countries' => [
'DE',
'AT'
],
'excludeCountries' => [
'GB'
],
'sourceCountry' => 'IT',
'address' => 'Via Roma 1, 20121 Milano, Italia',
'legalForm' => 'GmbH',
'identifier' => 'DE812345678',
'website' => 'https://example.fr'
],
'activeOnly' => false,
'stream' => false
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.topograph.co/v2/search/global"
payload := strings.NewReader("{\n \"query\": \"Bamberger GmbH, Wien\",\n \"name\": \"Bamberger GmbH\",\n \"hints\": {\n \"countries\": [\n \"DE\",\n \"AT\"\n ],\n \"excludeCountries\": [\n \"GB\"\n ],\n \"sourceCountry\": \"IT\",\n \"address\": \"Via Roma 1, 20121 Milano, Italia\",\n \"legalForm\": \"GmbH\",\n \"identifier\": \"DE812345678\",\n \"website\": \"https://example.fr\"\n },\n \"activeOnly\": false,\n \"stream\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.topograph.co/v2/search/global")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"Bamberger GmbH, Wien\",\n \"name\": \"Bamberger GmbH\",\n \"hints\": {\n \"countries\": [\n \"DE\",\n \"AT\"\n ],\n \"excludeCountries\": [\n \"GB\"\n ],\n \"sourceCountry\": \"IT\",\n \"address\": \"Via Roma 1, 20121 Milano, Italia\",\n \"legalForm\": \"GmbH\",\n \"identifier\": \"DE812345678\",\n \"website\": \"https://example.fr\"\n },\n \"activeOnly\": false,\n \"stream\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.topograph.co/v2/search/global")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"Bamberger GmbH, Wien\",\n \"name\": \"Bamberger GmbH\",\n \"hints\": {\n \"countries\": [\n \"DE\",\n \"AT\"\n ],\n \"excludeCountries\": [\n \"GB\"\n ],\n \"sourceCountry\": \"IT\",\n \"address\": \"Via Roma 1, 20121 Milano, Italia\",\n \"legalForm\": \"GmbH\",\n \"identifier\": \"DE812345678\",\n \"website\": \"https://example.fr\"\n },\n \"activeOnly\": false,\n \"stream\": false\n}"
response = http.request(request)
puts response.read_body{
"status": "resolved",
"summary": "Found in Austria: Bamberger GmbH (370916s).",
"query": {
"text": "Bamberger GmbH, Wien",
"name": "Bamberger GmbH",
"hints": {
"countries": [
"DE",
"AT"
],
"excludeCountries": [
"GB"
],
"sourceCountry": "IT",
"address": "Via Roma 1, 20121 Milano, Italia",
"legalForm": "GmbH",
"identifier": "DE812345678",
"website": "https://example.fr"
},
"latinName": "<string>",
"legalForm": "GmbH",
"likelyCountryCode": "KY"
},
"candidates": [
{
"rank": 123,
"match": "strong",
"countryCode": "AT",
"id": "370916s",
"legalName": "Bamberger GmbH",
"explanation": {
"summary": "<string>",
"reasons": [
{
"kind": "legal_form",
"text": "The register in Austria lists it under exactly that name",
"countryCode": "AT",
"url": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000764180"
}
]
},
"legalNameInEnglish": "<string>",
"companyNameTransliterations": [
"<string>"
],
"address": {
"addressLine1": "10 rue de la Fraternité",
"addressLine2": "Topograph Building",
"city": "Bagnolet",
"postalCode": "93170",
"region": "FR",
"countryCode": "FR",
"poBox": "PO Box 123",
"careOf": "c/o John Doe",
"state": "Île-de-France",
"latitude": 59.9139,
"longitude": 10.7522
},
"isActive": true
}
],
"countries": [
{
"countryCode": "DE",
"outcome": "match",
"explanation": "Germany: the register returned no company of that name."
}
],
"steps": [
{
"index": 123,
"kind": "reading_name",
"status": "running",
"label": "Asking the register in Austria",
"countryCode": "<string>"
}
],
"usage": {
"priceCents": 123,
"durationMs": 123
},
"reason": "not_a_legal_entity"
}{
"statusCode": 400,
"error": {
"code": "invalid_request",
"message": "name is required and cannot be empty"
}
}{
"statusCode": 402,
"error": {
"code": "insufficient_funds",
"message": "Not enough credits for a global search."
}
}{
"statusCode": 429,
"error": {
"code": "rate_limited",
"message": "Too many global searches this minute for this account. Retry shortly."
}
}{
"statusCode": 503,
"error": {
"code": "search_timeout",
"message": "The global search took too long to complete."
}
}Authorizations
Body
application/json
Free text: the company name plus anything you know, in one string ("Bamberger GmbH, Wien", "MFG Investments EOOD, from a UK filing", "Altria Group Inc., Richmond VA, altria.com"). The name and the hints are extracted for you. Give either query or name.
Example:
"Bamberger GmbH, Wien"
The company name alone, when you prefer to pass structured hints yourself. Legal-form suffixes, OCR noise and parenthesised aliases are handled.
Example:
"Bamberger GmbH"
Show child attributes
Show child attributes
Only companies the registers report as active.
Example:
false
Streaming mode: Server-Sent Events with progress events (the steps so far, and the candidates found so far), one complete event carrying the final response, or an error event. Set Accept to text/event-stream.
Example:
false
Response
The ranked candidates and the explained plan (JSON), or the SSE stream when stream is true.
resolved: one strong match. ambiguous: several plausible candidates, or one weak one. not_found: nothing acceptable; see reason.
Available options:
resolved, ambiguous, not_found The outcome in one sentence.
Example:
"Found in Austria: Bamberger GmbH (370916s)."
What was understood from your input.
Show child attributes
Show child attributes
Ranked candidates. Empty on not_found.
Show child attributes
Show child attributes
The countries considered, and what happened in each.
Show child attributes
Show child attributes
The search, step by step.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Why the search ended not_found, or why it stopped early.
Available options:
not_a_legal_entity, no_country_signal, country_not_covered, no_register_match, search_limit_reached, timeout