# North Data Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/northdata/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 1 credit per call |
| **Documentation** | https://www.piloterr.com/library/northdata-search |

## Description

Search North Data companies and people by name. Returns suggestion cards and pagination (1 credit).

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/northdata/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### BMW in France

```json
{
  "results": [
    {
      "url": "https://www.northdata.fr/Maison%20Boinaud%20SAS,%20Angeac-Champagne/Siren%20907120216",
      "name": "Maison Boinaud SAS",
      "type": "company",
      "location": "Angeac-Champagne",
      "position": 1
    }
  ],
  "pagination": {
    "next": null,
    "page": 1,
    "per_page": 15,
    "total_pages": null,
    "total_results": null
  }
}
```

## Documentation

## Overview
Search companies and people on **North Data** across `northdata.fr`, `northdata.com` and `northdata.de`. **1 credit** per call.

`query` is a name, or a full `suggest.json` URL. `countries` is optional (`FR` or `FR,DE`). `domain` selects the host for a keyword: `fr` (default), `com` or `de`.

The response is `{ results, pagination }`. Suggestions are one page of at most 15 rows, so `total_results` stays `null`. `page` greater than 1 returns 404.

## Quickstart
```
GET https://api.piloterr.com/v2/northdata/search?query=BMW&countries=FR
GET https://api.piloterr.com/v2/northdata/search?query=Siemens&domain=de&countries=DE
```

## `query`

**Example (keyword):**

    BMW

**Example (suggest URL):**

    https://www.northdata.fr/suggest.json?query=BMW&countries=FR

`query` is required.

| Form | Example | What happens |
|---|---|---|
| Name | `BMW` | Suggestions on the host chosen by `domain` (default `www.northdata.fr`) |
| Suggest URL | `https://www.northdata.de/suggest.json?query=Siemens&countries=DE` | Host, keyword and `countries` are read from the URL |

A company profile URL (any path other than `/` or `/suggest.json`) returns `400`. Pass that URL to [North Data Company](https://www.piloterr.com/library/northdata-company). Another host returns `400`. An empty value returns `400`.

`countries` filters the name search. Use ISO alpha-2 codes separated by comma, pipe or space: `FR`, `FR,DE`, `FR|DE`. Leave it empty to search every country. A code that is not two letters returns `400`. When `query` is a URL that already has `countries`, that value wins.

`domain` picks the host of a name: `fr` (default, `www.northdata.fr`), `com` or `en` (`www.northdata.com`), `de` (`www.northdata.de`). It is ignored when `query` is a URL. An unknown value returns `400`.

`page` only accepts `1`. Below 1 returns `400`. Above 1 returns `404`. A page holds at most 15 rows. `total_results`, `total_pages` and `next` stay null.

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Name, or a `suggest.json` URL on northdata.fr, .com or .de |
| `countries` | string | no | ISO alpha-2 codes (`FR` or `FR,DE`). Empty means every country |
| `domain` | string | no | `fr`, `com` or `de`. Ignored when `query` is a URL. Default `fr` |
| `page` | integer | no | Only `1` |

## Response fields
| Field | Type | Description |
|---|---|---|
| `results[]` | array | Suggestion cards |
| `results[].position` | integer | Position on the page, from 1 |
| `results[].name` | string | Company or person name |
| `results[].type` | string \| null | `company` or `person` |
| `results[].location` | string \| null | City, sometimes with the country |
| `results[].url` | string | Profile URL. Pass it to the company endpoint |
| `pagination.page` | integer | Always `1` |
| `pagination.per_page` | integer | Suggestion page size (`15`) |
| `pagination.total_results` | null | North Data does not return a total |
| `pagination.total_pages` | null | Single page |
| `pagination.next` | null | No next page |

## Notes
- A profile URL passed here returns `400`. Use [North Data Company](https://www.piloterr.com/library/northdata-company).
- No suggestion returns `404`, not an empty `200`.
- Pass `results[].url` to the company endpoint.

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing query, unknown host, bad country code, or a profile URL |
| `403` | Blocked |
| `404` | No suggestion, or `page` greater than 1 |
| `500` | Fetch failed |

## Related endpoints
- [North Data Company](https://www.piloterr.com/library/northdata-company)