CSV

CSV Response format

Vainu API can return responses in CSV format. Due to the native JSON structure of our data, this format requires additional considerations for structuring the CSV. With the CSV format, the fields parameter is used to define the header and data structure for the response.

📘

Define format

Vainu API responds in JSON by default. You can select CSV either by format=csv parameter or by header Accept: text/csv.

CSV format

The main factors in CSV format are encoding and delimiters used. Even though CSV should be separated by a comma, the support for delimiters varies by application. For example, Nordic Excels use semicolons by default. Vainu API formats the CSV with semicolons in ISO-8859-1 encoding, but you can change this with formatting parameters.

CSV Header and fields

Fields parameter has additional functionality compared to requests done with JSON responses. In addition to defining which fields should be returned, the fields parameter defines the structure of CSV content (header). The order of fields listed will be maintained in the CSV.

Defining the fields parameter does have some differences compared to JSON requests, as the data is converted from JSON to CSV. Basic fields containing strings, numbers, dates or other basic values work identically to JSON but subobjects, arrays and arrays of objects will need a different approach.

Basic values

Basic values are rendered as a single cell in CSV.

Subobjects

Subobject values can be targeted with dot notation. This applies to all basic values inside a subobject. For arrays you need to combine array techniques presented below.

<object_name>.<field_name>

Arrays of objects

When working with arrays, you have three options. You can either use indexes, find a subobject based on value or expand these objects to multiple rows.

Indexing works with array indexes beginning from 0. With the 0 you can target the first value or object within the array and so on.

<object_name>..<field_name>

Finding a subobject based on the value, allows you to find the object based on exact value. For example, you can find the financial statement with the preferred year or a specific Vainu custom industry.

<object_name>.<queried_field_name>$<queried_field_value>.<targeted_field_name>

Expanding the array ables you to get each subobject of the array on a separate row in the CSV. With this feature all the basic values and non-arrays will be copied on each row. For example you could get all the addresses with company names, where each row would have same company name and different address from this company.

Expanding the values works with separate fields_to_rows parameter that needs to be used in addition to fields parameter.

Examples of pointing fields to CSV-columns

Value inside list of sub-documents to column using sub-document matching

You can match to subdocuments using "sub_document.field$value.subdocument_field_name" pattern.

In this example f"fields=...vainu_custom_industry.value$Saas.confidence_score" means this column will be rendered value of "Saas" Vainu Custom Industry confidence score.

https://api.vainu.io/api/v2/companies/?country=FI&company_name__startswith=vainu&fields=business_id,company_name,domain,vainu_custom_industry.0.value,vainu_custom_industry.0.confidence_score,vainu_custom_industry.1.value,vainu_custom_industry.1.confidence_score&format=csv

Value inside list of sub-documents using list index value

You can also point to subdocuments using list index.

In this example vainu_custom_industry.1.confidence_score means that column has the confidence score of the second VCI in vainu_custom_industry list:

https://api.vainu.io/api/v2/companies/?country=FI&company_name__startswith=vainu&fields=domain,vainu_custom_industry.0.value,vainu_custom_industry.0.confidence_score,vainu_custom_industry.1.value,vainu_custom_industry.1.confidence_score&format=csv

Expand sub document list to rows in the CSV

Each Subdocument can be expanded to it's own row in the CSV using the field_to_rows parameter

In this example parameter field_to_rows=addresses expands each address to it's own row in the CSV.

https://api.vainu.io/api/v2/companies/?country=FI&company_name__startswith=vainu&format=csv&field_to_rows=addresses&fields=business_id,company_name,addresses.address,addresses.city,addresses.postal,addresses.address_country,addresses.visiting_address,addresses.visiting_city,addresses.visiting_postal,addresses.visiting_address_country,addresses.office_type,addresses.types,addresses.uid,technologies