Basedig API Documentation
Welcome to the Basedig API documentation! You can use our API to access basebook and basebookdata API endpoints.
You have some examples of server request in python and shell in the dark side area to the right.
Before using our API, be sure that you have every information that you need to request a token (YOUR_CLIENT_ID
, YOUR_CLIENT_SECRET
, YOUR_USERNAME
, YOUR_PASSWORD
).
Take care about how you use this API. There is quota of requests for each user.
Authentication
Make sure to replace
YOUR_CLIENT_ID
,YOUR_CLIENT_SECRET
,YOUR_USERNAME
,YOUR_PASSWORD
with your informations.To request a token, use this code:
import requests
response = requests.post(
"https://www.basedig.com/v1/o/token/",
data={
'grant_type': 'password',
'username': 'YOUR_USERNAME',
'password': 'YOUR_PASSWORD',
},
auth=requests.auth.HTTPBasicAuth(
'YOUR_CLIENT_ID',
'YOUR_CLIENT_SECRET'
)
)
token = response.json()
curl -X POST \
-d "client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=password&username=YOUR_USERNAME&password=YOUR_PASSWORD" \
https://www.basedig.com/v1/o/token/
Basedig uses Oauth2 to provide access to the API. You need a token to make your requests.
To request a token, use this url : https://www.basedig.com/v1/o/token/
You need to pass your username and password as parameter with client id and client secret.
Basedig expects the token to be included in all API requests to the server.
Basebooks
Get a specific basebook
Make sure to replace
YOUR_TOKEN
, with your token.
import requests
response = requests.get(
"https://www.basedig.com/v1/basebooks/1/",
headers={'Authorization': "Bearer YOUR_TOKEN",'content-type': 'application/json'}
)
curl -H "Authorization: Bearer YOUR_TOKEN" https://www.basedig.com/v1/basebooks/1/
The above command returns JSON structured like this:
[
{
"pk": 1,
"display_name": "Monthly commodities price history-year and month gold troy oz",
"display_url": "https://www.basedig.com/world-bank/monthly-commodities-price-history-year-and-month-gold-troy-o-1/",
"api_url": "https://www.basedig.com/v1/basebooks/1/",
"basebookdata": 1
}
]
This endpoint retrieves the specified basebook.
HTTP Request
GET https://www.basedig.com/v1/basebooks/<ID>/
Query Parameters
Parameter | Description |
---|---|
ID | The ID of the basebook to retrieve |
Add a basebook
Make sure to replace
YOUR_TOKEN
, with your token.
import requests
response = requests.post(
"http://www.basedig.com/v1/basebooks/",
headers={'Authorization': "Bearer YOUR_TOKEN", 'content-type': 'application/json'},
json={
"access_rights": 2,
"categories": [
"economy"
],
"columns": [
{
"date_format": "%Y-%m",
"db_type": "date",
"description": "",
"display_name": "Year and Month",
"index_key": "indexed",
"keywords": [
"month",
"and",
"year"
],
"name": "year_and_month"
},
{
"date_format": "",
"db_type": "double precision",
"description": "Gold (UK), 99.5% fine, London afternoon fixing, average of daily rates",
"display_name": "Gold ($/troy oz)",
"index_key": "name_only",
"keywords": [
"troy",
"gold",
"oz"
],
"name": "gold_troy_oz"
}
],
"content_orientation": "vertical",
"data_license": "CC-BY 4.0",
"description": "Monthly price data for the main commodities in the world. Database updated on a monthly basis. year and month gold troy oz ",
"display_name": "Monthly commodities price history-year and month gold troy oz ",
"keywords": [
"month",
"year",
"commodities",
"prices",
"price"
],
"language": "en-us",
"name": "monthly_commodities_price_history_year_and_month_gold_troy_o",
"related_basebooks": [],
"source": "WORLD BANK",
"data_collection_url": "http://www.google.fr",
"x_columns": [],
"y_columns": []
}
)
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{
"access_rights": 2,
"categories": [
"economy"
],
"columns": [
{
"date_format": "%Y-%m",
"db_type": "date",
"description": "",
"display_name": "Year and Month",
"index_key": "indexed",
"keywords": [
"month",
"and",
"year"
],
"name": "year_and_month"
},
{
"name": "gold_troy_oz",
"display_name": "Gold ($/troy oz)",
"date_format": "",
"index_key": "name_only",
"description": "Gold (UK), 99.5% fine, London afternoon fixing, average of daily rates",
"keywords": [
"troy",
"gold",
"oz"
],
"db_type": "double precision"
}
],
"content_orientation": "vertical",
"data_license": "CC-BY 4.0",
"description": "Monthly price data for the main commodities in the world. Database updated on a monthly basis. year and month gold troy oz ",
"display_name": "Monthly commodities price history-year and month gold troy oz ",
"keywords": [
"month",
"year",
"commodities",
"prices",
"price"
],
"language": "en-us",
"name": "monthly_commodities_price_history_year_and_month_gold_troy_o",
"related_basebooks": [],
"source": "WORLD BANK",
"data_collection_url": "http://www.google.fr",
"x_columns": [],
"y_columns": []
}' \
https://www.basedig.com/v1/basebooks/
The above command returns JSON structured like this:
[
{
"id": 1,
"source": "WORLD BANK",
"data_collection_url": "http://www.google.fr",
"name": "monthly_commodities_price_history_year_and_month_gold_troy_o",
"display_name": "Monthly commodities price history-year and month gold troy oz",
"description": "Monthly price data for the main commodities in the world. Database updated on a monthly basis. year and month gold troy oz",
"keywords": [
"month",
"year",
"commodities",
"prices",
"price"
],
"categories": [
"economy"
],
"content_orientation": "vertical",
"x_columns": [],
"y_columns": [],
"access_rights": 2,
"related_basebooks": [],
"language": "en-us",
"columns": [
{
"name": "gold_troy_oz",
"display_name": "Gold ($/troy oz)",
"date_format": "",
"index_key": "name_only",
"description": "Gold (UK), 99.5% fine, London afternoon fixing, average of daily rates",
"keywords": [
"troy",
"gold",
"oz"
],
"db_type": "double precision"
},
{
"name": "year_and_month",
"display_name": "Year and Month",
"date_format": "%Y-%m",
"index_key": "indexed",
"description": "",
"keywords": [
"month",
"year",
"and"
],
"db_type": "date"
}
],
"data_license": "CC-BY 4.0"
}
]
This endpoint allow you to add new basebook.
HTTP Request
POST https://www.basedig.com/v1/basebooks/
Fields description
-
access_rights:
- Type : Integer
- Description : Integer value which represent the level needed to access this basebook
- Allowed value list : 0, 1, 2, 3, 4, 5
- 0 : No access
- 1 : Basebook only
- 2 : Dataview only
- 3 : API access
- 4 : Download access
- 5 : Owner
- Default value : 2
- Required : True
-
categories:
- Type : List
- Description : List which must contains all the category of this basebook (as String).
- Required : False
-
columns:
- Type : List
- Description : List which contains dictionnaries which describes database columns of this basebook.
- Columns description:
- date_format : Format of the date you will use (as String), can be empty.
- db_type : Type in database (as String). Take care, here we talk about database type.
- description : Description of this columns (as String).
- display_name : String which is displayed for users.
- index_key : Define how the column is indexed. This field can have 3 value :
- none
- name_only (Default)
- indexed
- keywords : List of keywords related with this column (as String).
- name : String which define the name of the column in database.
- Columns description:
- Required : True
-
content_orientation:
- Type : String
- Description : String which indicate the orientation of the graph.
- Allowed value list : "horizontal" or "vertical"
- Default value : "vertical"
-
data_licence:
- Type : String
- Description : Licence used for this basebook.
- Required : True
-
description:
- Type : String
- Description : String used to describe this basebook.
- Required : False
-
display_name:
- Type : String
- Description : String we show when this basebook is searched or retrieve.
- Required : True
-
keywords:
- Type : List
- Description : List which contains keyword (as String) related to this basebook.
- Required : True
-
language:
- Type : String
- Description : Language used in this basebook.
- Allowed value list : All the ISO 639-1 standard language codes
- Required : True
-
name:
- Type : String
- Description : Name of this basebook
- Required : True
-
related_basebooks:
- Type : List
- Description : If the basebook you are registering is related with others basebooks, pass the id of others basebooks.
- Required : False
-
source:
- Type : String
- Description : Source of this basebook (site)
- Required : True
-
data_collection_url:
- Type : String (must match url regex)
- Description : URL where the data comes from
- Required : False
-
x_columns:
- Type : List
- Description : Data related to the basebook that you are creating. This will determine x-axis of the graph
- Required : True
-
y_columns:
- Type : List
- Description : Data related to the basebook that you are creating. This will determine y-axis of the graph
- Required : True
Search basebooks by keywords
Make sure to replace
YOUR_TOKEN
, with your token.
import requests
response = requests.get(
"https://www.basedig.com/v1/basebooks/search/?search=VALUE",
headers={'Authorization': "Bearer YOUR_TOKEN", 'content-type': 'application/json'}
)
curl -H "Authorization: Bearer YOUR_TOKEN" https://www.basedig.com/v1/basebooks/search/\?search=VALUE_SEARCHED
The above command returns JSON structured like this:
[
{
"count": 1,
"pagination": {
"pageSize": 10,
"pageCount": 1,
"current": 1,
"next": null,
"previous": null
},
"results": [
{
"pk": 1,
"display_name": "Monthly commodities price history-year and month gold troy oz",
"display_url": "https://www.basedig.com/world-bank/monthly-commodities-price-history-year-and-month-gold-troy-o-4/",
"api_url": "https://www.basedig.com/v1/basebooks/1/",
"basebookdata": 2
}
]
}
]
This endpoint retrieves all matched basebooks with these keywords.
HTTP Request
GET https://www.basedig.com/v1/basebooks/search/?search=VALUE
Example with pagination :
GET https://www.basedig.com/v1/basebooks/search/?search=VALUE&page=1
Example with multiple keywords :
GET https://www.basedig.com/v1/basebooks/search/?search=VALUE,VALUE2&page=1
GET Parameters
Parameter | Description | Defaults |
---|---|---|
Search | Value that you want to search in basebooks. Multiple words are allowed | Not any default provided |
Page | Allow you to paginate your results | Page 1 by default |
Basebookdatas
Get all the data of a specific basebookdata
Make sure to replace
YOUR_TOKEN
, with your token.
import requests
response = requests.get(
"https://www.basedig.com/v1/basebookdatas/1/",
headers={'Authorization': "Bearer YOUR_TOKEN",'content-type': 'application/json'}
)
curl --header "Authorization: Bearer YOUR_TOKEN" https://www.basedig.com/v1/basebookdatas/1/
The above command returns JSON structured like this:
[
{
"basebook": 1,
"data": {
"count": 2,
"pagination": {
"next": null,
"previous": null,
"current": 1,
"page_size": 50,
"pageCount": 1
},
"results": [
{
"Gold ($/troy oz)": 35.25,
"Year and Month": "1961-01-01"
},
{
"Gold ($/troy oz)": 35.25,
"Year and Month": "1961-02-01"
},
]
}
}
]
This endpoint retrieves the all the informations related to the specified basebookdata
HTTP Request
GET https://www.basedig.com/v1/basebookdatas/<ID>/
Example with pagination :
GET https://www.basedig.com/v1/basebookdatas/1/?page=1
Query Parameters
Parameter | Description | Defaults |
---|---|---|
ID | The ID of the basebookdata to retrieve | Not any default provided |
GET Parameters
Parameter | Description | Defaults |
---|---|---|
Page | Allow you to paginate your results | Page 1 by default |
Add a basebookdata
Make sure to replace
YOUR_TOKEN
, with your token.
import requests
response = requests.post(
"https://www.basedig.com/v1/basebookdatas/",
headers={'Authorization': "Bearer YOUR_TOKEN",'content-type': 'application/json'},
json={
"basebook": 1,
"data": {
"gold_troy_oz": {
"0": 35.27,
"1": 35.27
},
"year_and_month": {
"0": "1960-01",
"1": "1960-02"
}
}
}
)
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{
"basebook": 1,
"data": {
"gold_troy_oz": {
"0": 35.27,
"1": 35.27
},
"year_and_month": {
"0": "1960-01",
"1": "1960-02"
}
}
}' \
https://www.basedig.com/v1/basebookdatas/
The above command returns JSON structured like this:
[
{
"basebook": 1,
"data": {
"year_and_month": {
"0": "1960-01",
"1": "1960-02"
},
"gold_troy_oz": {
"0": 35.27,
"1": 35.27
}
}
}
]
This endpoint allow you to add new basebookdata.
HTTP Request
POST https://www.basedig.com/v1/basebookdatas/
Fields description
-
basebook:
- Type : Integer
- Description : ID of the basebook for which you want to add this basebookdata
- Required : True
-
data:
- Type : Dictionnary
- Description : Dictionnary which contains all the data related to the columns we created in basebook add.
- Required : True
NOTE
Take care, data that you pass to the API will be used to construct graph based on the columns created in basebook. Be sure that the column related to the data you want to create exist.
Errors
The Basedig API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request is invalid. |
401 | Unauthorized -- Your API key is wrong. |
403 | Forbidden -- The requested data is forbidden. |
404 | Not Found -- The specified data could not be found. |
405 | Method Not Allowed -- You tried to access data with an invalid method. |
406 | Not Acceptable -- You requested a format that isn't json. |
410 | Gone -- The data requested has been removed from our servers. |
429 | Too Many Requests -- You request the server too often. |
500 | Internal Server Error -- We had a problem with our server. Try again later. |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |