# JSON (API)
Sometimes you need to visualize data not contained in an RDBMS or NOSQL data store, but available from some HTTP API. For those times, the application provides the `JSON` data source.
The application treats all incoming data from the `JSON` data source as text; so you should be prepared to use [table formatting](https://docs.inverse.watch/user-guide/visualizations/table-visualization-options) when rendering the data.
The application treats all incoming data from the `JSON` data source as text; so you should be prepared to use [table formatting ](https://docs.inverse.watch/user-guide/visualizations/table-visualization-options)when rendering the data.
### 1. JSON Data Source Type
Use the `JSON` Data Source to query arbitrary JSON API’s. Setup is easy because no authentication is needed. Any RESTful JSON API will handle authentication through HTTP headers. So just create a new Data Source of type `JSON` and name it whatever you like (“JSON” is a good choice).
The application will detect data types supported by JSON (like numbers, strings, booleans), but others (mostly date/timestamp) will be treated as strings (unless specified in ISO-8601 format).
#### i. Usage
This Data Source takes queries in [YAML format](https://www.tutorialspoint.com/yaml/yaml_basics.htm). Here’s some examples using the GitHub API:
* Return a list of objects from an endpoint
```yaml
url: https://api.github.com/repos/getredash/redash/issues
```
This will return the result of the above API call as is.
Return a list of objects from an endpoint
* Return a single object
```yaml
url: https://api.github.com/repos/getredash/redash/issues/3495
```
The above API call returns a single object, and this object is being converted to a row.
Return a single object
* Return Specific Fields
In case you want to pick only specific fields from the resulting object(s), you can pass the `fields` option:
```yaml
url: https://api.github.com/repos/getredash/redash/issues
fields: [number, title]
```
Return Specific Fields
* Return an inner object
Many JSON API’s return arrays of nested objects. You can access an object in an array with the `path` key.
```yaml
url: https://api.github.com/repos/getredash/redash/issues/3495
path: assignees
```
The above query will use the `assignee` objects from the API result as the query result.
* Pass query string parameters
You can either craft your own URLs, or you can pass the `params` option:
```yaml
url: "https://api.github.com/search/issues"
params:
q: is:open type:pr repo:getredash/redash
sort: created
order: desc
```
The above is the same as:
```yaml
url: "https://api.github.com/search/issues?q=+is:open+type:pr+repo:getredash/redash&sort=created&order=desc"
```
* Additional HTTP Options
You can pass additional keys to modify various HTTP options:
* `method` - the HTTP method to use (default: `get`)
* `headers` - a dictionary of headers to send with the request
* `auth` - basic authentication username/password (should be passed as an array: `[username, password]`)
* `params` - a dictionary of query string parameters to add to the URL
* `data` - a dictionary of values to use as request body
* `json` - same as `data` except that it’s being converted to JSON
### 2. URL Data Source Type
{% hint style="warning" %}
You can use existing data sources created with this type, but you can’t create new ones. We recommend migrating to the JSON data source type.
{% endhint %}
The `URL` data source expects your endpoints to return JSON with a special data structure (see below).
#### i. Usage
The body of your query will include only the URL that returns data, for example:
```yaml
http://myserver/path/myquery
```
To manipulate the data (filter, sort, aggregate etc.) you can use the [Query Results Data Source](https://redash.io/help/user-guide/querying/query-results-data-source).
#### ii. Required Data Structure
The returned object must expose two keys: `columns` and `rows`.
* The `columns` key should expose an array of javascript objects describing the columns to be included in your data set. Each object will include three keys:
* `name`
* `type`
* `friendly_name`
* `rows` should return an array of javascript objects representing each row of data. The keys for each object should match the `name` keys described in your `columns` array.
The following data types are supported for columns:
* text
* integer
* float
* boolean
* string
* datetime
* date
An example of returned data appears below:
```javascript
{
"columns": [
{
"name": "date",
"type": "date",
"friendly_name": "date"
},
{
"name": "day_number",
"type": "integer",
"friendly_name": "day_number"
},
{
"name": "value",
"type": "integer",
"friendly_name": "value"
},
{
"name": "total",
"type": "integer",
"friendly_name": "total"
}
],
"rows": [
{
"value": 40832,
"total": 53141,
"day_number": 0,
"date": "2014-01-30"
},
{
"value": 27296,
"total": 53141,
"day_number": 1,
"date": "2014-01-30"
},
{
"value": 22982,
"total": 53141,
"day_number": 2,
"date": "2014-01-30"
}
]
}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.inverse.watch/user-guide/data-sources/json-api.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.