> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedatacity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Global Company Data API

> Company data for the United States, France, Germany and Ireland through one authenticated API.

One API gives you company data for the United States, France, Germany and Ireland. The endpoint
shape stays the same across all four markets. The classifications, identifiers and filters do not.

<Columns cols={3}>
  <Card title="4 markets" icon="globe">
    United States, France, Germany and Ireland.
  </Card>

  <Card title="11 endpoints" icon="code">
    The same API surface in every market.
  </Card>

  <Card title="1 API key" icon="key">
    Bearer authentication across the whole API.
  </Card>
</Columns>

<Info>
  **This API is in beta.** It is stable enough to build against and serves production data. Keys are
  issued by hand, there is no self-service signup yet, and a key currently reaches all four markets.
  Tell us what you need at [support@thedatacity.com](mailto:support@thedatacity.com) — feedback now
  shapes what ships next.
</Info>

<Note>
  This API does **not** serve UK company data. For the UK, use the
  [Industry Engine API](/api-reference/index).
</Note>

## Choose a market

Start with the market you want to query. Each tab shows values taken from that market's OpenAPI
document. Run the request at the end of the tab first: it returns the filter values that market
accepts, which you then use to build a company query.

<Tabs>
  <Tab title="United States">
    Base path: `/v1/us/`

    <Columns cols={2}>
      <Card title="Industry classification" icon="tags">
        Primary filter: `NAICS`

        Secondary filter: `RNAICS`
      </Card>

      <Card title="Company identifier" icon="building">
        Response field: `CompanyNumber`
      </Card>

      <Card title="Location" icon="location-dot">
        Top-level region filter: `State`

        Location filters: `State`, `Town`, `HQPostcode`
      </Card>

      <Card title="API surface" icon="code">
        **11 endpoints** and **47 company filter fields**.
      </Card>
    </Columns>

    <Warning>
      Use only classification and location values returned by this market's filters endpoint.
      An unrecognised value returns an empty result with `200`, so a typo is indistinguishable
      from a query that legitimately matches nothing.
    </Warning>

    ```bash cURL theme={null}
    curl --request GET \
      --url "https://global-api.thedatacity.com/v1/us/filters" \
      --header "Authorization: Bearer YOUR_KEY"
    ```
  </Tab>

  <Tab title="France">
    Base path: `/v1/fr/`

    <Columns cols={2}>
      <Card title="Industry classification" icon="tags">
        Primary filter: `NAFs`

        Secondary filter: **Not available in this market**
      </Card>

      <Card title="Company identifier" icon="building">
        Response field: `Siren`
      </Card>

      <Card title="Location" icon="location-dot">
        Top-level region filter: **Not available in this market**

        Location filters: `Commune`, `HQPostcode`
      </Card>

      <Card title="API surface" icon="code">
        **11 endpoints** and **40 company filter fields**.
      </Card>
    </Columns>

    <Warning>
      Use only classification and location values returned by this market's filters endpoint.
      An unrecognised value returns an empty result with `200`, so a typo is indistinguishable
      from a query that legitimately matches nothing.
    </Warning>

    ```bash cURL theme={null}
    curl --request GET \
      --url "https://global-api.thedatacity.com/v1/fr/filters" \
      --header "Authorization: Bearer YOUR_KEY"
    ```
  </Tab>

  <Tab title="Germany">
    Base path: `/v1/de/`

    <Columns cols={2}>
      <Card title="Industry classification" icon="tags">
        Primary filter: `WZs`

        Secondary filter: `RWZs`
      </Card>

      <Card title="Company identifier" icon="building">
        Response field: `CompanyNumber`
      </Card>

      <Card title="Location" icon="location-dot">
        Top-level region filter: `State`

        Location filters: `State`, `Town`, `HQPostcode`
      </Card>

      <Card title="API surface" icon="code">
        **11 endpoints** and **48 company filter fields**.
      </Card>
    </Columns>

    <Warning>
      Use only classification and location values returned by this market's filters endpoint.
      An unrecognised value returns an empty result with `200`, so a typo is indistinguishable
      from a query that legitimately matches nothing.
    </Warning>

    ```bash cURL theme={null}
    curl --request GET \
      --url "https://global-api.thedatacity.com/v1/de/filters" \
      --header "Authorization: Bearer YOUR_KEY"
    ```
  </Tab>

  <Tab title="Ireland">
    Base path: `/v1/ie/`

    <Columns cols={2}>
      <Card title="Industry classification" icon="tags">
        Primary filter: `NACEs`

        Secondary filter: `RNACEs`
      </Card>

      <Card title="Company identifier" icon="building">
        Response field: `CompanyNumber`
      </Card>

      <Card title="Location" icon="location-dot">
        Top-level region filter: `State`

        Location filters: `State`, `Town`, `HQPostcode`
      </Card>

      <Card title="API surface" icon="code">
        **11 endpoints** and **45 company filter fields**.
      </Card>
    </Columns>

    <Warning>
      Use only classification and location values returned by this market's filters endpoint.
      An unrecognised value returns an empty result with `200`, so a typo is indistinguishable
      from a query that legitimately matches nothing.
    </Warning>

    ```bash cURL theme={null}
    curl --request GET \
      --url "https://global-api.thedatacity.com/v1/ie/filters" \
      --header "Authorization: Bearer YOUR_KEY"
    ```
  </Tab>
</Tabs>

## Make your first request

<Steps>
  <Step title="Choose the market">
    Use `us`, `fr`, `de` or `ie` after `/v1/` in every path. A request never searches more than one
    market.
  </Step>

  <Step title="Send your API key">
    Pass your key as a bearer token. Select a market above and copy its cURL request.

    Requests without a valid key return `401`.
  </Step>

  <Step title="Discover valid values">
    Call `GET /filters` before you filter companies. It returns the classifications, locations and
    other values accepted by that market.
  </Step>

  <Step title="Query companies">
    Send values returned by `/filters` to `POST /companies`. Do not reuse classification or location
    values from another market.
  </Step>
</Steps>

<Columns cols={2}>
  <Card title="Rate limit" icon="gauge-high">
    Each key can make 60 requests per minute. A `429` response includes a `retry-after` header.
  </Card>

  <Card title="Production data" icon="shield-halved" type="warning">
    There is no sandbox key. These docs provide copyable cURL with a placeholder key and do not send
    requests from this page.
  </Card>
</Columns>

## Compare markets

Every market exposes the **same 11 endpoints**. What differs is the values they accept,
which is where integrations break: an unrecognised filter key returns an empty result rather
than an error, so a request written for one market can silently return nothing for another.

|                    | **United States**             | **France**              | **Germany**                   | **Ireland**                   |
| ------------------ | ----------------------------- | ----------------------- | ----------------------------- | ----------------------------- |
| Path segment       | `/v1/us/`                     | `/v1/fr/`               | `/v1/de/`                     | `/v1/ie/`                     |
| Industry codes     | `NAICS`                       | `NAFs`                  | `WZs`                         | `NACEs`                       |
| Secondary codes    | `RNAICS`                      | **Not available**       | `RWZs`                        | `RNACEs`                      |
| Company identifier | `CompanyNumber`               | `Siren`                 | `CompanyNumber`               | `CompanyNumber`               |
| Region filter      | `State`                       | **Not available**       | `State`                       | `State`                       |
| Location filters   | `State`, `Town`, `HQPostcode` | `Commune`, `HQPostcode` | `State`, `Town`, `HQPostcode` | `State`, `Town`, `HQPostcode` |
| Filter keys        | 47                            | 40                      | 48                            | 45                            |

<Warning>
  **France has no region filter and no secondary scheme.** “Not available” is a real answer, not
  a gap in this table. France filters location by `Commune` and `HQPostcode`; there is no `RNAF`
  equivalent of the other markets' secondary codes. A request carrying `State` against France
  matches nothing and returns `200`.
</Warning>

Generated from the four OpenAPI documents on 2026-08-20, so it cannot drift from what the API accepts.

## Common workflows

<Columns cols={2}>
  <Card title="Discover filters" icon="list">
    `GET /filters` lists the valid values for the selected market.
  </Card>

  <Card title="Search by name" icon="magnifying-glass">
    `GET /search` finds companies when you have a name rather than filter criteria.
  </Card>

  <Card title="Build a company list" icon="building">
    `POST /companies` filters companies and returns aggregate insights with the results.
  </Card>

  <Card title="Classify records" icon="tags">
    `POST /classification` adds market-specific classifications to company records.
  </Card>
</Columns>

## Endpoint reference

Use the market groups in the sidebar for parameters, request bodies and response schemas. Every
reference page comes from that market's OpenAPI document, so it matches what the API accepts.

## Connect an AI assistant

Each market also exposes a [Model Context Protocol](https://modelcontextprotocol.io) server. Use the
same API key and replace `COUNTRY_CODE` with `us`, `fr`, `de` or `ie`:

```text MCP endpoint theme={null}
https://global-api.thedatacity.com/v1/COUNTRY_CODE/mcp
```

Connect more than one market server when you want an assistant to compare countries.