# Latvia Company Taxes & Employees (VID) (`ayuki/latvia-company-taxes-employees-vid`) Actor

Taxes paid, payroll taxes and average employees for every Latvian company, from official VID open data (CC0). Filter by NACE, municipality, size. Sole traders excluded for GDPR.

- **URL**: https://apify.com/ayuki/latvia-company-taxes-employees-vid.md
- **Developed by:** [LV Data Tools](https://apify.com/ayuki) (community)
- **Categories:** Lead generation, Open source, Other
- **Stats:** 2 total users, 1 monthly users, 84.6% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Latvia VID Company Taxes & Employees — Uzņēmumu nodokļi un darbinieki

Get **taxes paid and average employee counts for Latvian companies** from the official **State Revenue Service (Valsts ieņēmumu dienests, VID)** open data on data.gov.lv. Receive structured JSON with English field names, EUR amounts and source references, ready for company research, spreadsheets and data joins.

**Start without configuring filters:** the default run returns up to **100 annual company-period records**, excludes sole traders and selects no fixed year. No source account, API key or proxy is needed. Export your Apify dataset as JSON, CSV or Excel.

### Latvian company tax data API / VID uzņēmumu nodokļu dati

- **Annual data:** total VID-administered taxes, personal income tax (IIN), social contributions (VSAOI), average employees, legal form, main-activity NACE and legal-address municipality.
- **Quarterly data:** the published quarterly CSV, including VAT paid and VAT refunded (PVN). By default, legal form, NACE and municipality are added from the latest available annual record for that company.
- **Filters:** company registration numbers, name, NACE prefixes, municipality or district, minimum employees and minimum taxes paid.
- **Consistent amounts:** source values in thousand EUR are converted to EUR; the original total is retained in `totalTaxesPaidThousandEurRaw`.
- **Traceable results:** each row identifies the tax period, source dataset, CSV resource and source modification timestamp.

A record represents **one company in one tax period**, so a company can appear more than once. Quarterly enrichment describes the latest available annual company record and may differ from the quarterly period. This is tax-contribution and employment data; see the disclaimer below for its limits.

### Company research and market analysis / Uzņēmumu izpēte un tirgus analīze

- **Company discovery:** identify legal entities by industry, region and reported headcount, such as IT companies with at least 10 employees.
- **Counterparty research:** compare a company's reported tax contribution and average employees across available periods.
- **Sector and regional analysis:** study employment and tax contributions by NACE activity or municipality.
- **Data enrichment:** join results to company-register or procurement datasets using `registrationNumber`.

### Quick start / Ātrais sākums

1. Open the Actor's **Input** tab and keep the defaults for a preview.
2. Click **Start**. The Actor downloads the annual CSV and saves the first 100 eligible rows in source order.
3. Open **Output**: use **Overview** for a compact comparison or **Detail** for tax breakdowns and source metadata.
4. Export the dataset as JSON, CSV or Excel. Add optional filters for your next run, or explicitly set `maxItems` to `0` for a complete export.

The preview is designed to finish in **under five minutes under normal source/network conditions**. It avoids optional filters that could eliminate every result. The complete CSV must still be downloaded, and source outages or slow downloads can delay or prevent a run; a fixed completion time cannot be guaranteed.

#### Default preview: 100 annual records

This is equivalent to an empty input `{}`:

```json
{
  "dataset": "annual",
  "maxItems": 100,
  "includeSoleTraders": false,
  "enrichQuarterlyWithAnnual": true
}
```

#### Company lookup by registration number / Uzņēmuma reģistrācijas numurs

Return available annual periods for two companies from the included sample:

```json
{
  "dataset": "annual",
  "registrationNumbers": ["40003004589", "40003016728"],
  "maxItems": 100
}
```

#### NACE industry and employee search / NACE nozares un darbinieku skaits

Find IT companies with at least 10 average employees in available annual periods:

```json
{
  "dataset": "annual",
  "naceCodes": ["62"],
  "minEmployees": 10,
  "maxItems": 100
}
```

To target one year, add `"taxYear": 2024` only if that year is present in the current source. An unavailable year or a restrictive combination of filters can return no records.

#### Quarterly taxes and VAT / Ceturkšņa nodokļi un PVN

Leave the year and quarter empty to use the published quarterly data:

```json
{
  "dataset": "quarterly",
  "enrichQuarterlyWithAnnual": true,
  "includeSoleTraders": false,
  "maxItems": 100
}
```

#### Full annual export

```json
{
  "dataset": "annual",
  "maxItems": 0,
  "includeSoleTraders": false
}
```

### Input reference / Ievades parametri

Different filters are combined with **AND**. Values within a registration-number list or NACE list are alternatives. All filters are optional and left empty by default.

| Field | Default | Meaning |
|---|---|---|
| `dataset` | `"annual"` | `annual` for available tax years or `quarterly` for the published quarterly CSV. |
| `maxItems` | `100` | Maximum matching company-period rows in source order. Explicit `0` means unlimited; this is not a ranking or unique-company limit. |
| `taxYear` | Unset | Restrict either dataset to an available tax year; omit for all years in the file. |
| `quarter` | Unset | Quarter 1–4 for quarterly data; ignored for annual data. Omit to avoid selecting an unavailable quarter. |
| `registrationNumbers` | Unset | List of company registration numbers as strings, preserving leading zeros. |
| `nameContains` | Unset | Case-insensitive company-name substring. |
| `naceCodes` | Unset | Main-activity prefixes, e.g. `["62"]` or `["4941"]`. Dots are removed before matching. |
| `municipality` | Unset | ATVK code or exact source name, case-insensitive. Example: `"010096"` or `"Ziemeļu rajons"`. Riga is split into districts; `"Rīga"` or `"010000"` does not match all districts. |
| `minEmployees` | Unset | Minimum average employees for the period; missing employee values are treated as zero for filtering. |
| `minTaxesPaid` | Unset | Minimum total taxes in EUR. Setting `0` excludes negative net totals. |
| `includeSoleTraders` | `false` | ⚠️ Enabling this outputs personal data of natural persons. See the privacy notice below. |
| `enrichQuarterlyWithAnnual` | `true` | Adds annual legal form, NACE and municipality to quarterly rows. The annual file is also loaded when sole traders are excluded or NACE/municipality filters are used, even if this toggle is `false`. |

### Sample output / VID datu piemērs

This complete annual record is copied from the included `sample_output.json` (100 sample records). It illustrates the output format and historical source values; it is not a promise of the same values in a future run.

```json
{
  "registrationNumber": "40003004589",
  "name": "Sabiedrība ar ierobežotu atbildību \"BALTIC TECHNOLOGY GROUP\"",
  "legalForm": "limited liability company (SIA)",
  "legalFormLv": "sabiedrība ar ierobežotu atbildību",
  "naceCode": "6210",
  "municipalityCode": "010096",
  "municipality": "Ziemeļu rajons",
  "year": 2024,
  "quarter": null,
  "period": "2024",
  "totalTaxesPaidEur": 400000.0,
  "totalTaxesPaidThousandEurRaw": 400.0,
  "personalIncomeTaxEur": 133870.0,
  "socialContributionsEur": 244130.0,
  "averageEmployees": 28,
  "source": "VID via data.gov.lv (annual, CC0-1.0)",
  "sourceUrl": "https://data.gov.lv/dati/lv/dataset/komersantu-ieprieksejos-tris-taksacijas-gados-samaksato-vid-administreto-nodoklu-kopsummas",
  "sourceResourceId": "a42d6e8c-1768-4939-ba9b-7700d4f1dd3a",
  "sourceLastModified": "2026-09-14T14:12:01.541668"
}
```

**Overview** shows registration number, name, tax period, municipality, NACE, average employees and total taxes. **Detail** includes every output field, including IIN, VSAOI, raw totals, legal forms and source provenance.

Quarterly rows also include `vatPaidEur` and `vatRefundedEur`; those fields are absent from annual rows. `quarter` is `null` for annual data. Missing numeric or enrichment values can be `null`. Registration numbers, NACE codes and ATVK codes remain strings. Source amounts have EUR 10 precision (0.01 thousand EUR); totals are net of refunds and can be negative. `sourceLastModified` is the source timestamp, not the Actor run time.

### Data freshness and coverage / VID atvērtie dati

Each run resolves the CSV resource through the official CKAN `package_show` API and selects the CSV with the most recent reported modification or creation timestamp. Refreshes published by VID are picked up on the next run without hard-coded download URLs. Data freshness and available periods follow VID's publication schedule; these are published period totals, not live transactions.

The Actor downloads the bulk CSV rather than relying on the CKAN datastore subset, then filters and saves normalized rows. Even a 100-record preview downloads the complete selected CSV. Quarterly runs with the default privacy settings also read the annual CSV to detect sole traders and enrich company information. Records on the exclusion list are dropped from every output.

The previous README recorded local benchmarks on **2026-10-12**: 4–8 seconds for filtered queries, about 112 seconds for 268,944 annual rows, and about 72 seconds for 141,883 enriched quarterly rows. These are historical local measurements; Apify startup time, network conditions, source size and export volume affect actual duration.

### Cost and pricing FAQ / Cena un izmaksas

#### What does a run cost? What is the price per 1,000 records?

Check the Actor's current **Pricing** information in Apify Store and the run's usage details in Apify Console. Actor charges, if applicable, depend on the listed pricing model; platform usage depends on your plan and resources used. There is no verified fixed price per 1,000 records in this repository, so this README does not quote a rate. See [Apify pricing](https://apify.com/pricing) for current platform plans.

#### Can I try it with Apify credits?

A preview can use any available credits on your account, subject to your plan and the Actor's current pricing. Start with `maxItems: 100`, inspect run usage, then choose a larger export. Available credits do not guarantee that every run is free.

#### How can I control runtime and cost?

Keep the 100-record preview for initial testing. Set a larger positive `maxItems` only when needed; explicit `0` enables a full export. A limit reduces rows processed and saved, but does not reduce the bulk CSV download. Annual previews need one CSV; quarterly runs with default privacy/enrichment settings need two. Disabling enrichment alone does not avoid the annual download while sole traders are excluded.

#### Why did my filtered run return no records?

The company, period or filter combination may not be present in the selected source. Start with the default preview and remove optional filters, especially `taxYear`, `quarter` and municipality. Use an exact district name or ATVK code rather than a city-wide Riga value. Missing NACE values cannot match a NACE filter. The Actor returns matching source rows and does not invent fallback records.

#### Where can I get help?

Open an issue on the Actor's Apify Store page with your input JSON, run ID and the behavior you expected. For data rights or exclusion requests, use the controller contact in the privacy notice below.

### Disclaimer

Per VID, this data is **informative only and has no legal force**. It is not an official certificate of tax compliance or tax debt status (for that, use VID's official services). Figures may be revised by VID. This actor is not affiliated with VID or data.gov.lv.

### Source and legal basis

- Source: State Revenue Service of Latvia (VID), published on the Latvian Open Data Portal: [annual](https://data.gov.lv/dati/lv/dataset/komersantu-ieprieksejos-tris-taksacijas-gados-samaksato-vid-administreto-nodoklu-kopsummas), [quarterly](https://data.gov.lv/dati/lv/dataset/nodoklu-maksataju-taksacijas-ceturksni-samaksato-vid-administreto-nodoklu-kopsummas). License CC0 1.0. Credit is given as a courtesy.
- VID publishes this data under the law "Par nodokļiem un nodevām" (On Taxes and Fees), **Article 18(1) clause 8¹** ([likumi.lv](https://likumi.lv/ta/id/33946)): publicity of tax collection.

### Privacy notice

Controller: **Artyom Kutnevskiy (trading as LV Data Tools), contact lvdatatools@gmail.com**. Version 0.3, 2026-10-14.

- **Controller (for the actor's design and default processing):** Artyom Kutnevskiy (trading as LV Data Tools), contact lvdatatools@gmail.com.
- **Roles:** the publisher (LV Data Tools) is controller for the Actor's own source collection and minimisation, and acts as processor for each user's run output under §5.2 of the Apify Standard Actor Contract, while the user is controller of that output and its reuse.
- **Data:** business data on legal entities (companies, partnerships, branches). By default, rows of **sole traders (Individuālais komersants)** are removed, because they are natural persons and their name and tax amounts are personal data. That is ~22.5k rows in the annual file. Quarterly rows are matched by reg. no. against the annual file, with a fallback on the "IK" name suffix.
- **Opt-in:** if you set `includeSoleTraders: true`, the output contains personal data. **You (the actor user) become an independent controller.** You need your own lawful basis (e.g. Art. 6(1)(f) with an assessment), must respect purpose limitation (tax-collection publicity is the original purpose), and must meet your own Art. 14 duties. Do not use it for profiling individuals or for direct marketing to natural persons without a lawful basis. The legitimate-interest assessment is available on request from lvdatatools@gmail.com.
- **Source:** VID public open data (Art. 14(2)(f)). **Retention:** the publisher stores nothing. Data lives only in your run's dataset under your Apify retention settings.
- **Rights and objections / exclusion requests:** email **lvdatatools@gmail.com** with the registration number (and, for a sole trader, proof that you are the person concerned). The reg. no. is added to `src/excluded_registration_numbers.txt` and its rows are dropped from all outputs from the next build on. The list is loaded at runtime on every run.

# Actor input Schema

## `dataset` (type: `string`):

Annual: available tax years with taxes, average employees, legal form, NACE and municipality. Quarterly: the latest published quarterly CSV, also including VAT paid/refunded. Available periods depend on VID; no fixed year is selected by default.

## `maxItems` (type: `integer`):

Default: 100 company-period records for a quick preview. Stops after this many matching rows in source order; this is not a ranking or a limit on unique companies. Set 0 explicitly for all matching records. The complete CSV is downloaded even for a small limit.

## `taxYear` (type: `integer`):

Optional year filter for either dataset, e.g. 2024. Leave empty to include all years available in the selected CSV. A year not present in the source returns no records.

## `quarter` (type: `integer`):

Optional quarterly filter: 1, 2, 3 or 4. Ignored for annual data. Leave empty to use the published quarterly data; an unavailable quarter returns no records.

## `registrationNumbers` (type: `array`):

Optional list of Latvian company registration numbers, supplied as strings to preserve leading zeros. Any listed number may match. Leave empty for all companies. Example: \["40003004589", "40003016728"].

## `nameContains` (type: `string`):

Optional case-insensitive substring of the company name, e.g. Helmes. Leave empty for no name filter. Combined with all other filters.

## `naceCodes` (type: `array`):

Optional list of main-activity NACE prefixes. Any prefix may match, e.g. \["62"] for IT or \["4941"] for road freight. Dots are removed before matching. Quarterly NACE comes from the latest available annual record; missing NACE cannot match this filter.

## `municipality` (type: `string`):

Optional ATVK code (e.g. 010096) or exact source name (e.g. Ziemeļu rajons), matched case-insensitively. Riga is split into districts; Rīga or 010000 does not select all Riga districts. Leading zeros in codes are tolerated. Leave empty for all regions.

## `minEmployees` (type: `integer`):

Optional minimum average employees in the selected period, e.g. 10. Leave empty for no headcount filter. Zero is treated as the employee count when the source value is missing.

## `minTaxesPaid` (type: `integer`):

Optional minimum total VID-administered taxes in EUR, e.g. 100000. Source values in thousand EUR are converted before filtering. Leave empty to keep all amounts, including negative net totals. Setting 0 excludes negative totals.

## `includeSoleTraders` (type: `boolean`):

⚠️ GDPR: sole traders are natural persons. Their names and tax amounts are personal data. Enable only with a lawful basis (e.g. a documented legitimate interest) and a specific purpose. You become a controller of that data. Default: excluded.

## `enrichQuarterlyWithAnnual` (type: `boolean`):

Default: true. Adds legal form, NACE and municipality from the latest annual record for each company, which may describe a different period. The annual CSV is also loaded when sole traders are excluded (the default), or when a NACE/municipality filter is used, even if this toggle is false. Turning it off alone does not avoid that download.

## Actor input object example

```json
{
  "dataset": "annual",
  "maxItems": 100,
  "taxYear": 2024,
  "registrationNumbers": [
    "40003004589",
    "40003016728"
  ],
  "nameContains": "Helmes",
  "naceCodes": [
    "62"
  ],
  "municipality": "010096",
  "minEmployees": 10,
  "minTaxesPaid": 100000,
  "includeSoleTraders": false,
  "enrichQuarterlyWithAnnual": true
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "dataset": "annual",
    "maxItems": 100,
    "includeSoleTraders": false,
    "enrichQuarterlyWithAnnual": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("ayuki/latvia-company-taxes-employees-vid").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "dataset": "annual",
    "maxItems": 100,
    "includeSoleTraders": False,
    "enrichQuarterlyWithAnnual": True,
}

# Run the Actor and wait for it to finish
run = client.actor("ayuki/latvia-company-taxes-employees-vid").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "dataset": "annual",
  "maxItems": 100,
  "includeSoleTraders": false,
  "enrichQuarterlyWithAnnual": true
}' |
apify call ayuki/latvia-company-taxes-employees-vid --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ayuki/latvia-company-taxes-employees-vid"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/7FgStSC8LqiQeQvsa/builds/kNEyHNbDJ92ojVzxO/openapi.json