### XML Response Example

Source: https://github.com/northdata/api/blob/master/doc/data-api-userguide/data-api-userguide.md

Example of an XML response when requesting company data with the 'output=xml' parameter.

```xml
<Company>
  <id>57514825</id>
  <name>
    <name>1000mikes AG</name>
    <legalForm>AG</legalForm>
  </name>
  <address>
    <street>Hansaplatz 4</street>
    <postalCode>20099</postalCode>
    <city>Hamburg</city>
    <country>DE</country>
    <lat>53.5541139</lat>
    <lng>10.0116615</lng>
  </address>
  <register>
    <city>Hamburg</city>
    <id>HRB 103038</id>
    <uniqueKey>12203550103038</uniqueKey>
  </register>
  <status>LIQUIDATION</status>
</Company>
```

--------------------------------

### Directory Structure Example

Source: https://github.com/northdata/api/blob/master/doc/data-export-guide/data-export-guide.md

This shows the typical directory structure for accessing export data, organized by country and data level.

```bash
- at-m
- at-l
- at-xl
- be-m
- be-l
etc.
```

--------------------------------

### Retrieve Company by Name and Address

Source: https://github.com/northdata/api/blob/master/doc/data-api-userguide/data-api-userguide.md

Example of a GET request to retrieve a specific company's details using its name and address. Ensure parameters are properly URL-encoded.

```HTTP
https://www.northdata.com/_api/company/v1/company?address=Hamburg&name=1000MIKES%20AG&api_key=XXXX_XXXX
```

```JSON
{
  "id": "57514825",
  "name": {
    "name": "1000mikes AG",
    "legalForm": "AG"
  },
  "address": {
    "street": "Hansaplatz 4",
    "postalCode": "20099",
    "city": "Hamburg",
    "country": "DE",
    "lat": 53.5541139,
    "lng": 10.0116615
  },
  "register": {
    "city": "Hamburg",
    "id": "HRB 103038",
    "uniqueKey": "12203550103038"
  },
  "status": "liquidation"
}
```

--------------------------------

### Person Data Example (JSON)

Source: https://github.com/northdata/api/blob/master/doc/data-api-refguide/index.html

Example JSON response for retrieving person data. This structure includes personal details, address information, and identifiers.

```json
{
  "address" : {
    "country" : "country",
    "lng" : 6.027456183070403,
    "city" : "city",
    "street" : "street",
    "postalCode" : "postalCode",
    "formattedValue" : "formattedValue",
    "state" : "state",
    "lat" : 0.8008281904610115
  },
  "deceased" : true,
  "blocked" : true,
  "birthYear" : 2,
  "name" : {
    "firstName" : "firstName",
    "lastName" : "lastName",
    "title" : "title"
  },
  "id" : "id",
  "birthDate" : "2000-01-23",
  "northDataUrl" : "northDataUrl"
}
```

--------------------------------

### Example JSON Data Payload

Source: https://github.com/northdata/api/blob/master/doc/data-api-refguide/index.html

This snippet shows an example of a JSON data payload for publications, including details about mentioned companies, their roles, and related persons.

```json
{
  "newPos" : "newPos",
  "publications" : [ {
    "date" : "2000-01-23",
    "internal" : "{}",
    "language" : "language",
    "source" : { },
    "originalLanguage" : "originalLanguage",
    "title" : "title",
    "mentionedCompanies" : {
      "items" : [ {
        "person" : {
          "address" : {
            "country" : "country",
            "lng" : 6.027456183070403,
            "city" : "city",
            "street" : "street",
            "postalCode" : "postalCode",
            "formattedValue" : "formattedValue",
            "state" : "state",
            "lat" : 0.8008281904610115
          },
          "deceased" : true,
          "blocked" : true,
          "birthYear" : 2,
          "name" : {
            "firstName" : "firstName",
            "lastName" : "lastName",
            "title" : "title"
          },
          "id" : "id",
          "birthDate" : "2000-01-23",
          "northDataUrl" : "northDataUrl"
        },
        "roles" : [ {
          "date" : "2000-01-23",
          "name" : "name",
          "demotion" : true,
          "type" : "Publisher",
          "dir" : "None",
          "announce" : true,
          "group" : "Succession"
        }, {
          "date" : "2000-01-23",
          "name" : "name",
          "demotion" : true,
          "type" : "Publisher",
          "dir" : "None",
          "announce" : true,
          "group" : "Succession"
        } ]
      }, {
        "person" : {
          "address" : {
            "country" : "country",
            "lng" : 6.027456183070403,
            "city" : "city",
            "street" : "street",
            "postalCode" : "postalCode",
            "formattedValue" : "formattedValue",
            "state" : "state",
            "lat" : 0.8008281904610115
          },
          "deceased" : true,
          "blocked" : true,
          "birthYear" : 2,
          "name" : {
            "firstName" : "firstName",
            "lastName" : "lastName",
            "title" : "title"
          },
          "id" : "id",
          "birthDate" : "2000-01-23",
          "northDataUrl" : "northDataUrl"
        },
        "roles" : [ {
          "date" : "2000-01-23",
          "name" : "name",
          "demotion" : true,
          "type" : "Publisher",
          "dir" : "None",
          "announce" : true,
          "group" : "Succession"
        }, {
          "date" : "2000-01-23",
          "name" : "name",
          "demotion" : true,
          "type" : "Publisher",
          "dir" : "None",
          "announce" : true,
          "group" : "Succession"
        } ]
      } ]
    },
    "northDataUrl" : "northDataUrl",
    "structure" : {
      "topics" : [ {
        "name" : "name",
        "type" : "Entry",
        "value" : "value"
      }, {
        "name" : "name",
        "type" : "Entry",
        "value" : "value"
      } ]
    },
    "filings" : [ {
      "city" : "city",
      "name" : "name",
      "id" : "id"
    }, {
      "city" : "city",
      "name" : "name",
      "id" : "id"
    } ],
    "blocked" : true,
    "publisher" : {
      "relatedPersons" : {
        "items" : [ {
          "person" : {
            "address" : {
              "country" : "country",
              "lng" : 6.027456183070403,
              "city" : "city",
              "street" : "street",
              "postalCode" : "postalCode",
              "formattedValue" : "formattedValue",
              "state" : "state",
              "lat" : 0.8008281904610115
            },
            "deceased" : true,
            "blocked" : true,
            "birthYear" : 2,
            "name" : {
              "firstName" : "firstName",
              "lastName" : "lastName",
              "title" : "title"
            },
            "id" : "id",
            "birthDate" : "2000-01-23",
            "northDataUrl" : "northDataUrl"
          },
          "roles" : [ {
            "date" : "2000-01-23",
            "name" : "name",
            "demotion" : true,
            "type" : "Publisher",
            "dir" : "None",
            "announce" : true,
            "group" : "Succession"
          }, {
            "date" : "2000-01-23",
            "name" : "name",
            "demotion" : true,
            "type" : "Publisher",
            "dir" : "None",
            "announce" : true,
            "group" : "Succession"
          } ]
        } ]
      }
    }
  } ]
}
```

--------------------------------

### get /search/v1/suggest

Source: https://github.com/northdata/api/blob/master/doc/data-api-refguide/index.html

Provides quick company and person suggestions based on an input query. This endpoint is useful for implementing auto-complete functionality.

```APIDOC
## GET /search/v1/suggest

### Description
Provides quick company and person suggestions for a given input query. This endpoint is useful for implementing auto-complete functionality.

### Method
GET

### Endpoint
/search/v1/suggest

### Query Parameters
- **query** (string) - Required - The query string to search for.
- **domain** (string) - Optional - Filters results to "company" or "person". If empty, searches all.
- **history** (boolean) - Optional - Includes former company names if true.
- **status** (string) - Optional - A list of valid statuses (e.g., "active", "terminated", "liquidation").
- **censor** (boolean) - Optional - Should be set to true when presenting content on a public website.
- **limit** (int32) - Optional - Maximum number of items to return.
- **output** (string) - Optional - The desired response format. Defaults to "json".

### Responses
#### Success Response (200)
- **SearchResults** - A successful response containing search suggestions.
```

--------------------------------

### Fetch Publications for Multiple German Sources

Source: https://github.com/northdata/api/blob/master/doc/data-api-userguide/data-api-userguide.md

This example shows how to fetch publications from multiple important sources for German companies: Hrb, Eb, Ut, and Ins. Each source requires a separate API call.

```url
https://www.northdata.com/_api/pub/v1/publications?minTimestamp=2017-03-14&maxTimestamp=2017-03-15&source=Hrb&apiKey=XXXX-XXXX
```

```url
https://www.northdata.com/_api/pub/v1/publications?minTimestamp=2017-03-14&maxTimestamp=2017-03-15&source=Eb&apiKey=XXXX-XXXX
```

```url
https://www.northdata.com/_api/pub/v1/publications?minTimestamp=2017-03-14&maxTimestamp=2017-03-15&source=Ins&apiKey=XXXX-XXXX
```

```url
https://www.northdata.com/_api/pub/v1/publications?minTimestamp=2017-03-14&maxTimestamp=2017-03-15&source=Ut&apiKey=XXXX-XXXX
```

--------------------------------

### Example Segment Codes Structure

Source: https://github.com/northdata/api/blob/master/doc/data-api-userguide/data-api-userguide.md

Illustrates the structure of the segmentCodes field, showing industry classification codes for different international standards.

```json
segmentCodes: {
  "wz" : [ "01.13.2" ],
  "uksic" : [ "01.13" ],
  "isic" : [ "0113" ],
  "nace" : [ "01.13" ],
  "naics" : [ "111991", "111211", "111411", "111219", "111419" ]
}
```

--------------------------------

### Example of Unique Company Call-up

Source: https://github.com/northdata/api/blob/master/doc/data-api-userguide/data-api-userguide.md

Demonstrates how multiple API calls to the same company within a month are counted as a single request. This applies even when using different API endpoints.

```HTTP
/company/v1/company?name=North%20Data%20GmbH&address=Hamburg
```

```HTTP
/company/v1/publications?name=North%20Data%20GmbH&address=Hamburg
```

--------------------------------

### Example JSON Payload for Financials

Source: https://github.com/northdata/api/blob/master/doc/data-api-refguide/index.html

This JSON structure details financial information, including dates, notes, and itemized values. It is used for reporting and analysis of financial data.

```json
{
  "financials" : {
    "date" : "2000-01-23",
    "note" : {
      "html" : "html",
      "text" : "text"
    },
    "consolidated" : true,
    "formattedDate" : "formattedDate",
    "source" : {
      "snippets" : [ {
        "title" : "title",
        "contentType" : "contentType",
        "content" : "content"
      }, {
        "title" : "title",
        "contentType" : "contentType",
        "content" : "content"
      } ],
      "publicationId" : "publicationId",
      "publicationTitle" : "publicationTitle",
      "publicationDate" : "2000-01-23",
      "auditorName" : "auditorName"
    },
    "items" : [ {
      "note" : "note",
      "unit" : "unit",
      "name" : "name",
      "formattedValue" : "formattedValue",
      "id" : "id",
      "value" : 1.4658129805029452
    }, {
      "note" : "note",
      "unit" : "unit",
      "name" : "name",
      "formattedValue" : "formattedValue",
      "id" : "id",
      "value" : 1.4658129805029452
    } ]
  }
}
```

--------------------------------

### Identify Person by Name, City, and Birth Date

Source: https://github.com/northdata/api/blob/master/doc/data-api-userguide/data-api-userguide.md

Demonstrates how to construct a GET request to retrieve a person's information using their first name, last name, address (city), and birth date. Ensure parameters are URL-encoded.

```http
https://www.northdata.com/_api/person/v1/person?firstName=Alfons&lastName=Schuhbeck&address=M%C3%BCnchen&birthDate=1949-05-02
```

--------------------------------

### Full API Request URL with Event Filtering

Source: https://github.com/northdata/api/blob/master/doc/data-api-userguide/data-api-userguide.md

A complete example of an API request URL that includes parameters for company identification, event retrieval, specific event types, and a maximum event count. An API key placeholder is also shown.

```URL
https://www.northdata.com/_api/company/v1/company?address=Hamburg&name=1000MIKES%20AG&events=true&eventType=NameChange|AddressChange&maxEvents=3&api_key=XXXX_XXXX
```

--------------------------------

### Example JSON Payload for Extras

Source: https://github.com/northdata/api/blob/master/doc/data-api-refguide/index.html

This JSON structure represents additional information or 'extras', including source details and a list of items with their values. It is used for supplementary data points.

```json
{
  "extras" : [ {
    "sourceUrl" : "sourceUrl",
    "sourceName" : "sourceName",
    "items" : [ {
      "formattedHtmlValue" : "formattedHtmlValue",
      "name" : "name",
      "id" : "id",
      "value" : "value"
    }, {
      "formattedHtmlValue" : "formattedHtmlValue",
      "name" : "name",
      "id" : "id",
      "value" : "value"
    } ]
  }, {
    "sourceUrl" : "sourceUrl",
    "sourceName" : "sourceName",
    "items" : [ {
      "formattedHtmlValue" : "formattedHtmlValue",
      "name" : "name",
      "id" : "id",
      "value" : "value"
    }, {
      "formattedHtmlValue" : "formattedHtmlValue",
      "name" : "name",
      "id" : "id",
      "value" : "value"
    } ]
  } ]
}
```

--------------------------------

### Billing Information Response Structure

Source: https://github.com/northdata/api/blob/master/doc/data-api-userguide/data-api-userguide.md

The JSON structure returned when querying billing information, showing the start and end dates of the period and the total number of requests.

```JSON
{
  "periodStart": "2024-02-01",
  "periodEnd": "2024-02-29",
  "numberOfRequests": 1234  
}
```

--------------------------------

### Filter Company Events by Type and Max Count

Source: https://github.com/northdata/api/blob/master/doc/data-api-userguide/data-api-userguide.md

Example of how to filter company events by type and set a maximum number of events to return. This is useful for managing response size.

```URL Parameters
events=true
eventType=NameChange|AddressChange
maxEvents=3
```

--------------------------------

### get /search/v1/universal

Source: https://github.com/northdata/api/blob/master/doc/data-api-refguide/index.html

Performs a universal search to find the best company and person matches for a given input query. It supports various optional parameters to filter and format the results.

```APIDOC
## GET /search/v1/universal

### Description
Provides best company and person matches for a given input query.

### Method
GET

### Endpoint
/search/v1/universal

### Parameters
#### Query Parameters
- **query** (string) - Required - The query string.
- **domain** (string) - Optional - Set to "company" for companies only, "person" for persons only, otherwise leave empty.
- **status** (string) - Optional - List of valid statuses (active, terminated, liquidation).
- **pos** (string) - Optional - If additional results shall be downloaded, set this to the value of the newPos attribute of the previous response.
- **censor** (string) - Optional - Should be set when presenting the content on a public website.
- **offset** (integer) - Optional - Offset of first item to return.
- **limit** (integer) - Optional - Maximum number of items to return.
- **output** (string) - Optional - Response format. Default: json.
- **history** (boolean) - Optional - True to include historical data.
- **financials** (boolean) - Optional - True to include financial data.
- **events** (boolean) - Optional - True to include event data.
- **eventTypes** (string) - Optional - Restrict which event types will be returned if events equals true.
- **maxEvents** (integer) - Optional - Maximum number of events to return.
- **relations** (boolean) - Optional - True to include related company and person data.
- **sheets** (boolean) - Optional - True to include company financial sheets (balance, earnings).
- **extras** (boolean) - Optional - True to include extra company data provided by 3rd parties.

### Responses
#### Success Response (200)
- **SearchResults** (object) - A successful response containing search results.
```

--------------------------------

### Example JSON Payload for History

Source: https://github.com/northdata/api/blob/master/doc/data-api-refguide/index.html

This JSON structure represents historical financial data, including dates and associated notes. It is used for tracking changes or past financial records.

```json
{
  "history" : {
    "financials" : [ {
      "date" : "2000-01-23",
      "note" : {

```

--------------------------------

### Example Company Relation Role

Source: https://github.com/northdata/api/blob/master/doc/data-api-userguide/data-api-userguide.md

An excerpt from the API response showing a company relation role. It includes details like the date, direction of the relationship, group type, name, and specific share information if financials are included.

```JSON
"roles": [
  {
    "date": "2015-06-10",
    "dir": "Source",
    "group": "Interest",
    "name": "Shareholder",
    "sharesNominal": {
      "unit": "EUR",
      "value": 120001.0
    },
    "sharesPercent": 100.0,
    "type": "Shareholder"
  }
]
```

--------------------------------

### Example JSON Payload for Address

Source: https://github.com/northdata/api/blob/master/doc/data-api-refguide/index.html

This JSON object represents an address, including country, city, street, postal code, and geographical coordinates. It is used for location-specific data.

```json
{
  "address" : {
    "country" : "country",
    "lng" : 6.027456183070403,
    "city" : "city",
    "street" : "street",
    "postalCode" : "postalCode",
    "formattedValue" : "formattedValue",
    "state" : "state",
    "lat" : 0.8008281904610115
  }
}
```

--------------------------------

### Example JSON Response for Data Query

Source: https://github.com/northdata/api/blob/master/doc/data-api-refguide/index.html

This JSON structure represents a typical response from a data query, including pagination details and a list of results. It showcases the nested structure of person and publication data.

```json
{
  "total" : 1,
  "offset" : 0,
  "nextPos" : "nextPos",
  "nextOffset" : 6,
  "results" : [ {
    "person" : {
      "address" : {
        "country" : "country",
        "lng" : 6.027456183070403,
        "city" : "city",
        "street" : "street",
        "postalCode" : "postalCode",
        "formattedValue" : "formattedValue",
        "state" : "state",
        "lat" : 0.8008281904610115
      },
      "deceased" : true,
      "blocked" : true,
      "birthYear" : 2,
      "name" : {
        "firstName" : "firstName",
        "lastName" : "lastName",
        "title" : "title"
      },
      "id" : "id",
      "birthDate" : "2000-01-23",
      "northDataUrl" : "northDataUrl"
    },
    "publication" : {
      "date" : "2000-01-23",
      "internal" : "{}",
      "language" : "language",
      "source" : { },
      "originalLanguage" : "originalLanguage",
      "title" : "title",
      "mentionedCompanies" : {
        "items" : [ {
          "person" : {
            "address" : {
              "country" : "country",
              "lng" : 6.027456183070403,
              "city" : "city",
              "street" : "street",
              "postalCode" : "postalCode",
              "formattedValue" : "formattedValue",
              "state" : "state",
              "lat" : 0.8008281904610115
            },
            "deceased" : true,
            "blocked" : true,
            "birthYear" : 2,
            "name" : {
              "firstName" : "firstName",
              "lastName" : "lastName",
              "title" : "title"
            },
            "id" : "id",
            "birthDate" : "2000-01-23",
            "northDataUrl" : "northDataUrl"
          },
          "roles" : [ {
            "date" : "2000-01-23",
            "name" : "name",
            "demotion" : true,
            "type" : "Publisher",
            "dir" : "None",
            "announce" : true,
            "group" : "Succession"
          }, {
            "date" : "2000-01-23",
            "name" : "name",
            "demotion" : true,
            "type" : "Publisher",
            "dir" : "None",
            "announce" : true,
            "group" : "Succession"
          } ]
        }, {
          "person" : {
            "address" : {
              "country" : "country",
              "lng" : 6.027456183070403,
              "city" : "city",
              "street" : "street",
              "postalCode" : "postalCode",
              "formattedValue" : "formattedValue",
              "state" : "state",
              "lat" : 0.8008281904610115
            },
            "deceased" : true,
            "blocked" : true,
            "birthYear" : 2,
            "name" : {
              "firstName" : "firstName",
              "lastName" : "lastName",
              "title" : "title"
            },
            "id" : "id",
            "birthDate" : "2000-01-23",
            "northDataUrl" : "northDataUrl"
          },
          "roles" : [ {
            "date" : "2000-01-23",
            "name" : "name",
            "demotion" : true,
            "type" : "Publisher",
            "dir" : "None",
            "announce" : true,
            "group" : "Succession"
          }, {
            "date" : "2000-01-23",
            "name" : "name",
            "demotion" : true,
            "type" : "Publisher",
            "dir" : "None",
            "announce" : true,
            "group" : "Succession"
          } ]
        } ]
      },
      "northDataUrl" : "northDataUrl",
      "structure" : {
        "topics" : [ {
          "name" : "name",
          "type" : "Entry",
          "value" : "value"
        }, {
          "name" : "name",
          "type" : "Entry",
          "value" : "value"
        } ]
      },
      "filings" : [ {
        "city" : "city",
        "name" : "name",
        "id" : "id"
      }, {
        "city" : "city",
        "name" : "name",
        "id" : "id"
      } ],
      "blocked" : true,
      "publisher" : {
        "relatedPersons" : {
          "items" : [ {
            "person" : {
              "address" : {
                "country" : "country",
                "lng" : 6.027456183070403,
                "city" : "city",
                "street" : "street",
                "postalCode" : "postalCode",
                "formattedValue" : "formattedValue",

```

--------------------------------

### get /company/v1/company

Source: https://github.com/northdata/api/blob/master/doc/data-api-refguide/index.html

Retrieve a company's information, with options to filter by name, address, registration details, and include various data types like financials, events, and relations.

```APIDOC
## GET /company/v1/company

### Description
Retrieve a company's information. This endpoint allows for detailed querying by company name, address, registration details, and can include historical data, financial information, events, and related entities.

### Method
GET

### Endpoint
`/company/v1/company`

### Parameters
#### Query Parameters
- **name** (string) - Optional - Company name.
- **address** (string) - Optional - Company address (city).
- **registerId** (string) - Optional - The ID under which the company is registered (e.g., HRB 12345).
- **registerCity** (string) - Optional - The city of the court where the company is registered (e.g., Hamburg).
- **companyId** (string) - Optional - Internal company ID (may change over time).
- **fuzzyMatch** (boolean) - Optional - True to find the best match (similar name and nearby address).
- **registerKey** (string) - Optional - Key provided via the register uniqueKey field.
- **history** (boolean) - Optional - True to include historical data.
- **financials** (boolean) - Optional - True to include financial data.
- **events** (boolean) - Optional - True to include event data.
- **eventTypes** (string) - Optional - Restrict which event types will be returned if events equals true.
- **maxEvents** (integer) - Optional - Maximum number of events to return.
- **relations** (boolean) - Optional - True to include related company and person data.
- **sheets** (boolean) - Optional - True to include company financial sheets (balance, earnings).
- **extras** (boolean) - Optional - True to include extra company data provided by 3rd parties.
- **output** (string) - Optional - Response format (default: json).

### Return type
[Company](#Company)
```

--------------------------------

### get /search/v1/power

Source: https://github.com/northdata/api/blob/master/doc/data-api-refguide/index.html

Performs a power search for companies, supporting various geo and financial criteria. This endpoint allows filtering companies based on name, description, location, legal form, financial data, and event history.

```APIDOC
## GET /search/v1/power

### Description
Performs a power search for companies, supporting various geo and financial criteria. This endpoint allows filtering companies based on name, description, location, legal form, financial data, and event history.

### Method
GET

### Endpoint
/search/v1/power

### Query Parameters
- **name** (string) - Optional - Company name or empty.
- **description** (string) - Optional - wz code or keywords to match in the company's subject.
- **address** (string) - Optional - Address or geo coordinates.
- **maxDistanceKm** (double) - Optional - Maximum distance from given address.
- **legalForm** (list) - Optional - List of legal forms.
- **financialId** (list) - Optional - List of financial IDs for financial filtering.
- **lowerBound** (double) - Optional - List of lower bounds for financial filterings.
- **upperBound** (double) - Optional - List of upper bounds for financial filterings.
- **eventType** (list) - Optional - List of event types for event filtering.
- **minDate** (date) - Optional - List of minimum dates for event filterings.
- **maxDate** (date) - Optional - List of maximum dates for event filterings.
- **status** (list) - Optional - List of valid statuses (active, terminated, liquidation).
- **history** (boolean) - Optional - True to include historical data.
- **financials** (boolean) - Optional - True to include financial data.
- **events** (boolean) - Optional - True to include event data.
- **eventTypes** (list) - Optional - Restrict which event types will be returned if events equals true.
- **maxEvents** (int32) - Optional - Maximum number of events to return.
- **relations** (boolean) - Optional - True to include related company and person data.
- **sheets** (boolean) - Optional - True to include company financial sheets (balance, earnings).
- **extras** (boolean) - Optional - True to include extra company data provided by 3rd parties.
- **pos** (string) - Optional - If additional results shall be downloaded, set this to the value of the newPos attribute of the previous response.
- **censor** (boolean) - Optional - Should be set when presenting the content on a public website.
- **limit** (int32) - Optional - Maximum number of items to return.
- **output** (string) - Optional - Response format (default: json).

### Return Type
[SearchResults](#SearchResults)
```

--------------------------------

### Example JSON Payload for Related Persons

Source: https://github.com/northdata/api/blob/master/doc/data-api-refguide/index.html

This JSON structure represents data for related persons, including their personal details, addresses, and roles. It is typically used when querying for individuals associated with a subject.

```json
{
  "relatedPersons" : {
    "items" : [ { 
      "person" : {
        "address" : {
          "country" : "country",
          "lng" : 6.027456183070403,
          "city" : "city",
          "street" : "street",
          "postalCode" : "postalCode",
          "formattedValue" : "formattedValue",
          "state" : "state",
          "lat" : 0.8008281904610115
        },
        "deceased" : true,
        "blocked" : true,
        "birthYear" : 2,
        "name" : {
          "firstName" : "firstName",
          "lastName" : "lastName",
          "title" : "title"
        },
        "id" : "id",
        "birthDate" : "2000-01-23",
        "northDataUrl" : "northDataUrl"
      },
      "roles" : [ {
        "date" : "2000-01-23",
        "name" : "name",
        "demotion" : true,
        "type" : "Publisher",
        "dir" : "None",
        "announce" : true,
        "group" : "Succession"
      }, {
        "date" : "2000-01-23",
        "name" : "name",
        "demotion" : true,
        "type" : "Publisher",
        "dir" : "None",
        "announce" : true,
        "group" : "Succession"
      } ]
    }, { 
      "person" : {
        "address" : {
          "country" : "country",
          "lng" : 6.027456183070403,
          "city" : "city",
          "street" : "street",
          "postalCode" : "postalCode",
          "formattedValue" : "formattedValue",
          "state" : "state",
          "lat" : 0.8008281904610115
        },
        "deceased" : true,
        "blocked" : true,
        "birthYear" : 2,
        "name" : {
          "firstName" : "firstName",
          "lastName" : "lastName",
          "title" : "title"
        },
        "id" : "id",
        "birthDate" : "2000-01-23",
        "northDataUrl" : "northDataUrl"
      },
      "roles" : [ {
        "date" : "2000-01-23",
        "name" : "name",
        "demotion" : true,
        "type" : "Publisher",
        "dir" : "None",
        "announce" : true,
        "group" : "Succession"
      }, {
        "date" : "2000-01-23",
        "name" : "name",
        "demotion" : true,
        "type" : "Publisher",
        "dir" : "None",
        "announce" : true,
        "group" : "Succession"
      } ]
    } ]
  }
}
```

--------------------------------

### get /person/v1/person

Source: https://github.com/northdata/api/blob/master/doc/data-api-refguide/index.html

Retrieve a person's details. This endpoint allows fetching information about a person using various optional query parameters such as name, address, birth date, and ID. It can also include historical data and related company information.

```APIDOC
## GET /person/v1/person

### Description
Retrieve a person.

### Method
GET

### Endpoint
/person/v1/person

### Query Parameters
- **firstName** (string) - Optional - Query Parameter — first name(s) of a person
- **lastName** (string) - Optional - Query Parameter — last name of a person
- **address** (string) - Optional - Query Parameter — person address (you only need to specify the city)
- **birthDate** (string) - Optional - Query Parameter — birth date format: date
- **personId** (string) - Optional - Query Parameter — internal person id (do not store this id in an external database, it may change over time)
- **history** (boolean) - Optional - Query Parameter — true to include historical data
- **relations** (boolean) - Optional - Query Parameter — true to include related company data
- **output** (string) - Optional - Query Parameter — response format default: json

### Response
#### Success Response (200)
- **address** (object) - Description
- **deceased** (boolean) - Description
- **blocked** (boolean) - Description
- **birthYear** (integer) - Description
- **name** (object) - Description
- **id** (string) - Description
- **birthDate** (string) - Description
- **northDataUrl** (string) - Description

### Request Example
```json
{
  "address" : {
    "country" : "country",
    "lng" : 6.027456183070403,
    "city" : "city",
    "street" : "street",
    "postalCode" : "postalCode",
    "formattedValue" : "formattedValue",
    "state" : "state",
    "lat" : 0.8008281904610115
  },
  "deceased" : true,
  "blocked" : true,
  "birthYear" : 2,
  "name" : {
    "firstName" : "firstName",
    "lastName" : "lastName",
    "title" : "title"
  },
  "id" : "id",
  "birthDate" : "2000-01-23",
  "northDataUrl" : "northDataUrl"
}
```
```

--------------------------------

### Test Data Zip File Naming Convention

Source: https://github.com/northdata/api/blob/master/doc/data-export-guide/data-export-guide.md

Illustrates the naming convention for test data zip files, indicating generation date, city, country, data level, format, and language.

```bash
testdata20230630-innsbruck-AT-M-de.csv.zip
testdata20230630-innsbruck-AT-M-de.jsonl.zip
testdata20230630-innsbruck-AT-M-en.csv.zip
testdata20230630-innsbruck-AT-M-en.jsonl.zip
```

--------------------------------

### Fetch Publications for a Specific Day and Source

Source: https://github.com/northdata/api/blob/master/doc/data-api-userguide/data-api-userguide.md

Use this URL to retrieve all publications for a given day and source. Adjust the dates and API key as needed. It's recommended to run this daily to fetch the previous day's publications.

```url
https://www.northdata.com/_api/pub/v1/publications?minTimestamp=2017-03-14&maxTimestamp=2017-03-15&source=Hrb&apiKey=XXXX-XXXX
```

--------------------------------

### Configure Auto-complete Suggestions

Source: https://github.com/northdata/api/blob/master/doc/data-api-userguide/data-api-userguide.md

Set parameters for auto-complete suggestions, including domain, status, countries, and history. 'censor' should be set to true for public forms.

```text
domain=company
status=active|liquidation
countries=DE|CH
history=false
censor=true
```

--------------------------------

### get /pub/v1/publications

Source: https://github.com/northdata/api/blob/master/doc/data-api-refguide/index.html

Retrieve publications. At most 10 publications are returned with each call. For more, repeat the call setting the pos parameter to the newPos attribute value of the response.

```APIDOC
## GET /pub/v1/publications

### Description
Retrieve publications. At most 10 publications are returned with each call. For more, repeat the call setting the pos parameter to the newPos attribute value of the response.

### Method
GET

### Endpoint
/pub/v1/publications

### Query Parameters
- **minTimestamp** (date-time) - Optional - minimum datetime publication was added to the database
- **maxTimestamp** (date-time) - Optional - maximum datetime publication was added to the database
- **minDate** (date) - Optional - DEPRECATED - please use minTimestamp instead
- **maxDate** (date) - Optional - DEPRECATED - please use maxTimestamp instead
- **sources** (string) - Optional - restrict which sources are allowed for the returned publications
- **content** (boolean) - Optional - whether to include publication text / html (may significantly slow down response)
- **publisherHistory** (boolean) - Optional - true to include historical data for the publisher
- **publisherFinancials** (boolean) - Optional - true to include financial data for the publisher
- **publisherRelations** (boolean) - Optional - true to include related company and person data for the publisher
- **publisherEvents** (boolean) - Optional - true to include event data for the publisher
- **publisherExtras** (boolean) - Optional - true to include extra publisher data provided by 3rd parties
- **publisherSheets** (boolean) - Optional - true to include publisher sheets (balance, earnings)
- **pos** (string) - Optional - if additional results shall be downloaded, set this to the value of the newPos attribute of the previous response
- **censor** (boolean) - Optional - should be set when presenting the content on a public website
- **output** (string) - Optional - response format default: json

### Responses
#### Success Response (200)
A successful response [GenericResponse](#GenericResponse)

### Return type
[GenericResponse](#GenericResponse)
```

--------------------------------

### Suggest (Auto Complete)

Source: https://github.com/northdata/api/blob/master/doc/data-api-userguide/data-api-userguide.md

Optimized for implementing auto-complete functionality in input boxes.

```APIDOC
## GET /_api/search/v1/suggest

### Description
Optimized for implementing auto-complete functionality in input boxes.

### Method
GET

### Endpoint
https://www.northdata.com/_api/search/v1/suggest

### Parameters
#### Query Parameters
- **query** (string) - Required - The search query string for auto-completion.

### Response
#### Success Response (200)
- **suggestions** (list) - A list of auto-complete suggestions.
```

--------------------------------

### get /company/v1/publications

Source: https://github.com/northdata/api/blob/master/doc/data-api-refguide/index.html

Retrieve the publications associated with a company. This endpoint supports filtering by company name, address, registration details, and more, as well as pagination and output format selection.

```APIDOC
## GET /company/v1/publications

### Description
Retrieve the publications associated with a company.

### Method
GET

### Endpoint
/company/v1/publications

### Parameters
#### Query Parameters
- **name** (string) - Optional - company name
- **address** (string) - Optional - company address (you only need to specify the city)
- **registerId** (string) - Optional - the ID of under which the company is registered, for example HRB 12345
- **registerCity** (string) - Optional - the city of the court where the company is registered, for example Hamburg
- **companyId** (string) - Optional - internal company id (do not store this id in an external database, it may change over time)
- **fuzzyMatch** (boolean) - Optional - true to find best match (similar name and nearby address)
- **registerKey** (string) - Optional - key that has been provided via the register uniqueKey field
- **sources** (string) - Optional - restrict which sources are allowed for the returned publications
- **content** (string) - Optional - whether to include publication text / html (may significantly slow down response)
- **censor** (string) - Optional - should be set when presenting the content on a public website
- **offset** (int32) - Optional - offset of first item to return
- **limit** (int32) - Optional - maximum number of items to return
- **output** (string) - Optional - response format default: json

### Response
#### Success Response (200)
- **Company** (object) - A successful response containing company information.

### Response Example
{
  "example": "{\"publications\": [ { \"title\": \"Publication Title\", \"date\": \"2023-10-27\" } ]}"
}
```

--------------------------------

### Full Quarterly Export Zip File Naming Convention

Source: https://github.com/northdata/api/blob/master/doc/data-export-guide/data-export-guide.md

Details the naming convention for full quarterly export zip files, including date, country, data level, format, language, and split variant.

```bash
export2023Q3-AT-M-de.csv.zip
export2023Q3-AT-M-de.jsonl.zip
export2023Q3-AT-M-en.csv.zip
export2023Q3-AT-M-en.jsonl.zip
export2023Q3-AT-M-de.csv.split.zip
export2023Q3-AT-M-de.jsonl.split.zip
export2023Q3-AT-M-en.csv.split.zip
export2023Q3-AT-M-en.jsonl.split.zip
```

--------------------------------

### Identify Company by Name and City

Source: https://github.com/northdata/api/blob/master/doc/data-api-userguide/data-api-userguide.md

Use 'name' and 'address' parameters to identify a company. Ensure parameters are URL-encoded for requests.

```text
name=1000MIKES AG
address=Hamburg
```

```text
name=1000MIKES%20AG&address=Hamburg
```

--------------------------------

### Reference Overview Endpoint

Source: https://github.com/northdata/api/blob/master/doc/data-api-userguide/data-api-userguide.md

This general-purpose endpoint returns all available reference data, excluding data that is too verbose or specific for general inclusion.

```APIDOC
## GET /_api/reference/v1/overview

### Description
Returns meta information about the service, including available countries, sources, role types, etc. This endpoint is useful for dynamically determining available options for features like power search.

### Method
GET

### Endpoint
https://www.northdata.com/_api/reference/v1/overview

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **data** (object) - A JSON object containing various reference data categories.
```

--------------------------------

### API Key Authentication via HTTP Header

Source: https://github.com/northdata/api/blob/master/doc/data-api-userguide/data-api-userguide.md

Method 1 for API authentication: passing the API key as an HTTP header. This method is recommended for production.

```http
X-Api-Key: XXXX-XXXX
```

--------------------------------

### Identify Company by Internal Company ID (Discouraged)

Source: https://github.com/northdata/api/blob/master/doc/data-api-userguide/data-api-userguide.md

While possible, using 'companyId' is discouraged due to potential changes over time. Prefer the 'registerKey' for stable identification.

```text
companyId=<company_id>
```

--------------------------------

### Enable Fuzzy Matching

Source: https://github.com/northdata/api/blob/master/doc/data-api-userguide/data-api-userguide.md

Set 'fuzzyMatch=true' to enable probabilistic matching for companies when exact identification is uncertain.

```text
fuzzyMatch=true
```

--------------------------------

### Identify Company by Register Key

Source: https://github.com/northdata/api/blob/master/doc/data-api-userguide/data-api-userguide.md

Use the 'registerKey' parameter for a single, stable identifier for German companies, simplifying references and database storage.

```text
registerKey=12203550103038
```