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.
| Paramenter | Description | Default value |
|---|---|---|
| encoding | Encoding of the resulting file. For example utf-8 or iso-8859-1 | iso-8859-1 |
| delimiter | Coming soon! CSV column delimiter | ; (semicolon) |
| format | Preferred response format. Available formats: json / jsonl /csv | json |
| csv_quoting | nonnumeric: Numbers are not wrapped in quotes. none: CSV cells are not wrapped in quotes. Line breaks are removed. all: All CSV cells are wrapped in quotes. minimal: Only values that require quoting are wrapped in quotes. | nonnumeric |
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.
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:
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.
Updated almost 2 years ago