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.

You must replace YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, YOUR_USERNAME, YOUR_PASSWORD with your informations.

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.
- 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.