NAV Navbar
shell python

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

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


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.