# Dokumentasjon for API

## Kom i gang

Send JSON til `https://firmalisten.no/company/search`. Bruk API-tokenet fra [Innstillinger](https://firmalisten.no/innstillinger) med Pro eller Max.

```sh
curl 'https://firmalisten.no/company/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer DITT_API_TOKEN' \
  --data '{
    "query": "rørlegger",
    "filter": { "county_code": "03" },
    "page": 1
  }'
```

## Parametere

Alle felt er valgfrie. `{}` søker uten søketekst eller filtre.

| Felt | Type | Beskrivelse |
| --- | --- | --- |
| `query` | string | Søketekst. Standard: `""`. |
| `filter` | object | Filtre kombinert med OG. |
| `sort` | object | Feltnavn med `"asc"` eller `"desc"`. |
| `page` | integer | Sidenummer fra `1`. Standard: `1`. |
| `limit` | integer | Kun Max: `1`–`100`. Standard: `20`. Utelates med Pro. |

Søket dekker organisasjonsnummer, navn og virksomhetsbeskrivelse. Alle søkeord må matche; skrivefeil rettes ikke. Andre parametere, som `fields`, `size` og `offset`, ignoreres.

## Filtre

En verdi betyr likhet. En liste betyr ELLER. Ulike felt og flere operatorer på samme felt kombineres med OG.

```json
{
  "filter": {
    "county_code": ["03", "32"],
    "type_code": "AS",
    "employees": { "gte": 5, "lte": 50 },
    "has_email": true
  }
}
```

Dette gir aksjeselskaper i Oslo eller Akershus med 5–50 ansatte og e-postadresse.

| Operator | Betydning | Operator | Betydning |
| --- | --- | --- | --- |
| `eq` | Lik | `ne` | Ulik |
| `gt` | Større enn | `gte` | Større enn eller lik |
| `lt` | Mindre enn | `lte` | Mindre enn eller lik |

Bruk strenger for koder, tall for tallfelt og `true` / `false` for boolske felt. Tomme verdilister og operatorobjekter avvises. Se [filterfeltene](#filterfelt), [NACE-koder](https://firmalisten.no/hjelp/bransjekoder) og [fylkes- og kommunekoder](https://firmalisten.no/hjelp/fylkekoder).

## Sortering

```json
{
  "sort": {
    "employees": "desc",
    "name": "asc"
  }
}
```

Feltene prioriteres i angitt rekkefølge, før tekstlig relevans. Bruk `asc` eller `desc`. Alle [filterfelt](#filterfelt) unntatt `roles` og `tags` kan brukes, uavhengig av abonnement. Uten `sort` brukes tekstlig relevans, så `relevance` synkende og `orgnr` stigende.

## Svar og paginering

HTTP 200 med `ok: true`. Eksempel med ett fiktivt firma:

```json
{
  "ok": true,
  "data": {
    "hits": [
      {
        "orgnr": "123456789",
        "name": "Eksempel Rørlegger AS",
        "industry1_name": "VVS-arbeid",
        "county_name": "Oslo",
        "website": "https://example.com",
        "registered_at": "2020-01-15T00:00:00.000Z",
        "employees": 12,
        "relevance": 100
      }
    ],
    "query": "rørlegger",
    "processing_time_ms": 2,
    "hits_per_page": 10,
    "page": 1,
    "total_pages": 1,
    "total_hits": 1
  }
}
```

| Felt i `data` | Innhold |
| --- | --- |
| `hits` | Firma på siden. `[]` ved ingen treff. |
| `query` | Søketeksten. |
| `processing_time_ms` | Søkemotorens behandlingstid i ms. |
| `hits_per_page` | Valgt sidestørrelse. |
| `page` | Gjeldende sidenummer. |
| `total_pages` | Antall sider. |
| `total_hits` | Totalt antall treff. |

Firmafeltene er vist i eksemplet: `employees` og `relevance` er tall, øvrige felt er strenger. Felt kan mangle eller være `null`. E-post og telefon returneres ikke.

Øk `page` med 1, og behold resten av søket. Stopp ved `total_pages` eller tom `hits`. Data kan endres mellom forespørslene.

## Bruksgrenser

| Tilgang | Treff per side | Per sekund¹ | Per minutt |
| --- | --- | --- | --- |
| Pro | 10 | 1 | 100 |
| Max | 20, opptil 100 med `limit` | 5 | 300 |

¹ Med gyldig API-token. Grensene deles per konto. Kun Max kan angi `limit`.

## Feil

Kontroller både HTTP-status og `ok`.

| HTTP | Svar | Handling |
| --- | --- | --- |
| `200` | `ok: false`, `message`, eventuelt `fields` | Rett parametrene eller håndter søkefeilen. |
| `400` | Ugyldig forespørsel | Kontroller JSON og HTTP-headere. |
| `429` | Teksten `Too many requests` | Vent før neste forsøk. |

`fields` inneholder valideringsfeil per parameter. Eksempel: Pro støtter ikke filter på `email`.

```json
{
  "ok": false,
  "message": "Valideringsfeil",
  "fields": {
    "filter": ["Field \"email\" is not available on your plan"]
  }
}
```

Søkefeil har `message`, uten `fields`. Feilsvar er ikke alltid JSON.

## Filterfelt

### Pro

| Type | Felt |
| --- | --- |
| Boolean | `is_new`, `is_active`, `has_employees`, `has_website`, `has_email`, `has_phone` |
| Number | `income`, `employees` |
| String | `type_code`, `industry1_code`, `county_code`, `municipality_code` |

### Max

Alle feltene ovenfor, pluss:

| Type | Felt |
| --- | --- |
| Identitet | `orgnr`, `name`, `type_name`, `main_unit`, `lang`, `summary` |
| Forretningsadresse | `ba_street`, `ba_area_name`, `ba_area_code`, `ba_municipality_name`, `ba_municipality_code`, `ba_county_name`, `ba_county_code`, `ba_country_name`, `ba_country_code` |
| Postadresse | `pa_street`, `pa_area_name`, `pa_area_code`, `pa_municipality_name`, `pa_municipality_code`, `pa_county_name`, `pa_county_code`, `pa_country_name`, `pa_country_code` |
| Geografi | `municipality_name`, `county_name`, `country_name`, `country_code` |
| Bransje og sektor | `industry1_name`, `industry2_name`, `industry2_code`, `industry3_name`, `industry3_code`, `sector_name`, `sector_code`, `industry_name`, `industry_code` |
| Kontakt | `phone`, `mobile`, `fax`, `website`, `email`, `contact` |
| Number | `equity`, `expenses`, `result`, `debt`, `assets`, `accounting_year`, `last_accounting_year`, `relevance` |
| Boolean | `bankrupt`, `closed`, `shut`, `in_company_registry`, `in_vat_registry`, `in_foundation_registry`, `in_voluntary_registry`, `has_contact_data`, `has_accounting_data`, `has_reserved`, `reserved_mobile`, `reserved_phone` |
| Date | `registered_at`, `founded_at`, `last_hire_at`, `created_at`, `updated_at` |
| Array | `roles`, `tags` |

Identitet, adresser, geografi, bransje og kontakt er tekstfelt. `ba_` er forretningsadresse; `pa_` er postadresse. `industry1_code` er primær NACE-kode. Virtuelle felt som `search` og `counties`, samt `_id`, kan ikke brukes som filtre.