Getting started
Exploring and using data
Exploring catalogs and datasets
Exploring a catalog of datasets
What's in a dataset
Filtering data within a dataset
An introduction to the Explore API
An introduction to the Automation API
Introduction to the WFS API
Downloading a dataset
Creating maps and charts
Creating advanced charts with the Charts tool
Overview of the Maps interface
Configure your map
Manage your maps
Reorder and group layers in a map
Creating multi-layer maps
Share your map
Navigating maps made with the Maps interface
Rename and save a map
Creating pages with the Code editor
How to limit who can see your visualizations
Archiving a page
Managing a page's security
Creating a page with the Code editor
Content pages: ideas, tips & resources
How to insert internal links on a page or create a table of contents
Sharing and embedding a content page
How to troubleshoot maps that are not loading correctly
Creating content with Studio
Creating content with Studio
Adding a page
Publishing a page
Editing the page layout
Configuring blocks
Previewing a page
Adding text
Adding a chart
Adding an image block to a Studio page
Adding a choropleth map block in Studio
Adding a points of interest map block in Studio
Adding a key performance indicator (KPI)
Configuring page information
Using filters to enhance your pages
Refining data
Managing page access
How to edit the url of a Studio page
Adding a map block in Studio
Visualizations
Managing saved visualizations
Configuring the calendar visualization
The basics of dataset visualizations
Configuring the images visualization
Configuring the custom view
Configuring the table visualization
Configuring the map visualization
Understanding automatic clustering in maps
Configuring the analyze visualization
Publishing data
Publishing datasets
Creating a dataset
Creating a dataset from a local file
Creating a dataset with multiple files
Creating a dataset from a remote source (URL, API, FTP)
Creating a dataset using dedicated connectors
Creating a dataset with media files
Federating an Opendatasoft dataset
Publishing a dataset
Publishing data from a CSV file
Publishing data in JSON format
Supported file formats
Promote mobility data thanks to GTFS and other formats
Configuring datasets
Automated removal of records
Configuring dataset export
Checking dataset history
Configuring the tooltip
Dataset actions and statuses
Dataset limits
Defining a dataset schema
How Opendatasoft manages dates
How and where Opendatasoft handles timezones
How to find your workspace's IP address
Keeping data up to date
Processing data
Translating a dataset
How to configure an HTTP connection to the France Travail API
Deciding what license is best for your dataset
Types of source files
OpenStreetMap files
Shapefiles
JSON files
XML files
Spreadsheet files
RDF files
CSV files
MapInfo files
GeoJSON files
KML/KMZ files
GeoPackage
Connectors
Saving and sharing connections
Airtable connector
Amazon S3 connector
ArcGIS connector
Azure Blob storage connector
Database connector
Dataset of datasets (workspace) connector
Eco Counter connector
Feed connector
Google BigQuery connector
Google Drive connector
How to find the Open Agenda API Key and the Open Agenda URL
JCDecaux connector
Netatmo connector
OpenAgenda connector
Realtime connector
Salesforce connector
SharePoint connector
U.S. Census connector
WFS connector
Databricks connector
Harvesters
Harvesting a catalog
ArcGIS harvester
ArcGIS Hub Portals harvester
CKAN harvester
CSW harvester
FTP with meta CSV harvester
Opendatasoft Federation harvester
Quandl harvester
Socrata harvester
data.gouv.fr harvester
data.json harvester
Processors
What is a processor and how to use one
Add a field processor
Compute geo distance processor
Concatenate text processor
Convert degrees processor
Copy a field processor
Correct geo shape processor
Create geo point processor
Decode HTML entities processor
Decode a Google polyline processor
Deduplicate multivalued fields processor
Delete record processor
Expand JSON array processor
Expand multivalued field processor
Expression processor
Extract HTML processor
Extract URLs processor
Extract bit range processor
Extract from JSON processor
Extract text processor
File processor
GeoHash to GeoJSON processor
GeoJoin processor
Geocode with ArcGIS processor
Geocode with BAN processor (France)
Geocode with PDOK processor
Geocode with the Census Bureau processor (United States)
Geomasking processor
Get coordinates from a three-word address processor
IP address to geo Coordinates processor
JSON array to multivalued processor
Join datasets processor
Meta expression processor
Nominatim geocoder processor
Normalize Projection Reference processor
Normalize URL processor
Normalize Unicode values processor
Normalize date processor
Polygon filtering processor
Replace text processor
Replace via regular expression processor
Retrieve Administrative Divisions processor
Set timezone processor
Simplify Geo Shape processor
Skip records processor
Split text processor
Transform boolean columns to multivalued field processor
Transpose columns to rows processor
WKT and WKB to GeoJson processor
what3words processor
Data Collection Form
About the Data Collection Form feature
Data Collection Forms associated with your Opendatasoft workspace
Create and manage your data collection forms
Sharing and moderating your data collection forms
Dataset metadata
Analyzing how your data is used
Getting involved: Sharing, Reusing and Reacting
Discovering & submitting data reuses
Sharing through social networks
Commenting via Disqus
Submitting feedback
Following dataset updates
Sharing and embedding data visualizations
Monitoring usage
An overview of monitoring your workspaces
Analyzing user activity
Analyzing actions
Detail about specific fields in the ods-api-monitoring dataset
How to count a dataset's downloads over a specific period
Analyzing data usage
Analyzing a single dataset with its monitoring dashboard
Analyzing back office activity
Using the data lineage feature
Managing your users
Managing limits
Managing users
Managing users
Setting quotas for individual users
Managing access requests
Inviting users to the portal
Managing workspaces
Managing your portal
Configuring your portal
Configure catalog and dataset pages
Configuring a shared catalog
Sharing, reusing, communicating
Customizing your workspace's URL
Managing legal information
Connect Google Analytics (GA4)
Regional settings
Pictograms reference
Managing tracking
Look & Feel
Branding your portal
Customizing portal themes
How to customize my portal according to the current language
Managing the dataset themes
Configuring data visualizations
Configuring the navigation
Adding IGN basemaps
Adding assets
Plans and quotas
Managing security
Configuring your portal's overall security policies
A dataset's Security tab
Mapping your directory to groups in Opendatasoft (with SSO)
Single sign-on with OpenID Connect
Single sign-on with SAML
Parameters
- Home
- Publishing data
- Types of source files
- JSON files
JSON files
Updated by Anthony Pépin
JSON is an open-standard format that uses human-readable text to transmit data objects consisting of key-value pairs. It is the most common data format to build web APIs.
As JSON documents can have a lot of different forms, the platform can extract data from JSON files, JSON Lines files, and JSON dictionaries.
JSON File
You can use a JSON file as a source. From this file, the platform extracts a valid JSON document (array or object) into one dataset of several records:
- If the document is a JSON array, a record will be created for each object inside the array (the keys will be used as column names).
- If the document is a JSON object, the "JSON root" parameter should contain a dot-separated path to the array inside your object. If not provided, the platform tries
items
.
For each item inside the array, the platform can follow another path before extracting the records with the parameter "JSON object".
Supported field types
- Regular fields (decimal, boolean, string)
- JSON object: used as-is
- Array:
- If the array contains JSON objects, it is used as-is.
- If the array contains strings, a multivalued field is created with all the strings separated by a semicolon (
;
).
Creation
For more information about adding a file source, see Retrieving a file.
Configuration
Name | Description | Usage |
JSON root | ijson path to the JSON array that contains the objects to be extracted as dataset records ijson is a syntax to navigate inside JSON objects. It consists of separating the attribute names with dots (for example, ). More features are available for advanced users. | If the JSON array is at the root of the document, leave the JSON root box empty. If the JSON file is a JSON object, enter the ijson path to the array in the JSON root box. |
JSON object | Relative path to the JSON object to extract | After setting the JSON root, if the preview shows irrelevant columns, and that the JSON object has been extracted as the value of one column, enter the name of that column in the JSON object box. |
Name | Description | Usage |
Extract filename | Creates a new column with the name of the source file. | By default, this option is toggled off. Toggle on this option to extract the file name in an additional column. |
Examples
Example 1:
[
{
"name": "Agra Express",
"origin": "Agra Cantt",
"destination": "New Delhi"
},
{
"name": "Gour Express",
"origin": "Balurghat",
"destination": "Sealdah"
}
]
In this JSON file, the JSON array is directly at the root. You can leave the JSON root box empty.
The resulting dataset will be:
name | origin | destination |
Agra Express | Agra Cantt | New Delhi |
Gour Express | Balurghat | Sealdah |
Example 2:
{
"filename": "trains.json",
"content": {
"trains": [
{
"id": 123,
"info": {
"name": "Agra Express",
"origin": "Agra Cantt",
"destination": "New Delhi"
}
},
{
"id": 555,
"info": {
"name": "Gour Express",
"origin": "Balurghat",
"destination": "Sealdah"
}
}
]
}
}
For this complex JSON file, the correct JSON root is content.trains
. If content.trains
is set as the JSON root, the resulting dataset will be:
id | info |
123 | {"origin": "Agra Cantt", "destination": "New Delhi", "name": "Agra Express"} |
555 | {"origin": "Balurghat", "destination": "Sealdah", "name": "Gour Express"} |
To only extract the info
JSON objects, and skip the id
number, the correct JSON object is info
. If info
is set as a JSON object, the resulting dataset will be:
name | origin | destination |
Agra Express | Agra Cantt | New Delhi |
Gour Express | Balurghat | Sealdah |
JSON Lines
You can use a JSON Lines file as a source. In JSON Lines files, each line is a one-line JSON document. The whole file is not a valid JSON document but each line is.
Two modes are supported:
- One JSON array on each line (or one array altogether)
- One JSON object on each line
Supported field types
- Regular fields (decimal, string)
- Array: used as-is
- JSON object: used as-is
Creation
For more information about adding a file source, see Retrieving a file.
Configuration
Name | Description | Usage |
Extract filename | Creates a new column with the name of the source file. | By default, this option is toggled off. Toggle on this option to extract the file name in an additional column. |
First line number | For files that do not start at the first line, it is possible to define which line is considered the first one. The lines above will be skipped from the dataset. | By default, the dataset starts at line 1. Enter the number of the line that should be considered the beginning of the dataset. |
Headers | For files whose first line contains field names | By default, this option is toggled on. It makes the values of the first line field labels. Toggle off this option if the first line doesn't contain field names but data: the field labels will then be empty by default. |
JSON Dict
You can use a JSON dictionary as a source. The platform extracts a valid JSON document (array or object) into one dataset of several records.
The platform expects a JSON object where each key contains a record. The platform then creates records with:
- one column to hold the key
- one column for each attribute of the corresponding object (or a single column named "value" if the value is a string instead of an object).
Supported field types
- Regular fields (decimal, bool, string)
- JSON object: will be used as-is
- Array:
- If the array contains JSON objects, it is used as-is.
- If the array contains strings, a multivalued field is created with all the strings separated by a semicolon (
;
).
Creation
For more information about adding a file source, see Retrieving a file.
Configuration
Name | Description | Usage |
Extract filename | Creates a new column with the name of the source file. | By default, this option is toggled off. Toggle on this option to extract the file name in an additional column. |
JSON root | ijson path to the JSON array that contains the objects to be extracted as dataset records ijson is a syntax to navigate inside JSON objects. It consists of separating the attribute names with dots (for example, ). More features are available for advanced users. | If the JSON array is at the root of the document, leave the JSON root box empty. If the JSON file is a JSON object, enter the ijson path to the array in the JSON root box. |
Key field name | Label of the "key" column | The default value is "key". Enter the new label of the "key" column in the Key field name box. It will modify both the label and the technical identifier of the column. |
Examples
Example 1:
{
"2016": {
"type1": {
"price": 10,
"color": "blue",
"available": true
},
"type2": {
"price": 9,
"color": "red",
"available": true
}
},
"2015": {
"type1": {
"price": 10.5,
"color": "teal",
"available": true
},
"type2": {
"price": 9.1,
"color": "crimson",
"available": true
}
}
}
If you leave the JSON root box empty, the resulting dataset will be:
key | type1 | type2 |
2016 | {"color": "blue", "available": true, "price": 10} | {"color": "red", "available": true, "price": 9} |
2015 | {"color": "teal", "available": true, "price": 10.5} | {"color": "crimson", "available": true, "price": 9.1} |
Example 2:
{
"results": {
"datasets": [{
"abc": {
"title": "A B C",
"description": "A description about ABC"
}
},
{
"xyz": {
"title": "D E F",
"description": "Another description"
}
}
]
}
}
For this complex JSON file, the correct JSON root is results.datasets.item
.
results.datasets
leads to the arrayitem
iterates inside the array and gets each object
key | description | title |
abc | A description about ABC | A B C |
xyz | Another description | D E F |