Developer Guide
v8 (v7 Rails, v1 Django/Laravel)
Search
K
Links
Comment on page

Create an API-based Chart

Creating an API-based Chart

Sometimes, charts data are complicated and closely tied to your business. Forest Admin allows you to code how the chart is computed. Choose API as the data source when configuring your chart.
Forest Admin will make the HTTP call to Smart Chart URL when retrieving the chart values for the rendering.

Value API-based Chart

On our Live Demo, we have a MRR value chart which computes our Monthly Recurring Revenue. This chart queries the Stripe API to get all charges made in the current month (in March for this example).
SQL
Mongodb
Rails
Django
Laravel
When serializing the data, we use the Liana.StatSerializer() serializer. Check the value syntax below.
{ value: <number> }
/routes/dashboard.js
const P = require('bluebird');
const express = require('express');
const router = express.Router();
const Liana = require('forest-express-sequelize');
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
const moment = require('moment');
...
router.post('/stats/mrr', (req, res) => {
let mrr = 0;
let from = moment.utc('2018-03-01').unix();
let to = moment.utc('2018-03-31').unix();
return stripe.charges
.list({
created: { gte: from, lte: to }
})
.then((response) => {
return P.each(response.data, (charge) => {
mrr += charge.amount;
});
})
.then(() => {
let json = new Liana.StatSerializer({
value: mrr
}).perform();
res.send(json);
});
});
...
module.exports = router;
When serializing the data, we use the Liana.StatSerializer() serializer. Check the value syntax below.
{ value: <number> }
/routes/dashboard.js
const P = require('bluebird');
const express = require('express');
const router = express.Router();
const Liana = require('forest-express-mongoose');
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
const moment = require('moment');
...
router.post('/stats/mrr', (req, res) => {
let mrr = 0;
let from = moment.utc('2018-03-01').unix();
let to = moment.utc('2018-03-31').unix();
return stripe.charges
.list({
created: { gte: from, lte: to }
})
.then((response) => {
return P.each(response.data, (charge) => {
mrr += charge.amount;
});
})
.then(() => {
let json = new Liana.StatSerializer({
value: mrr
}).perform();
res.send(json);
});
});
...
module.exports = router;
When serializing the data, we use the serialize_model() method. Check the value syntax below.
{ value: <number> }
/config/routes.rb
Rails.application.routes.draw do
# MUST be declared before the mount ForestLiana::Engine.
namespace :forest do
post '/stats/mrr' => 'charts#mrr'
end
mount ForestLiana::Engine => '/forest'
end
/app/controllers/forest/charts_controller.rb
class Forest::ChartsController < ForestLiana::ApplicationController
def mrr
mrr = 0
from = Date.parse('2018-03-01').to_time(:utc).to_i
to = Date.parse('2018-03-31').to_time(:utc).to_i
Stripe::Charge.list({
created: { gte: from, lte: to },
limit: 100
}).each do |charge|
mrr += charge.amount / 100
end
stat = ForestLiana::Model::Stat.new({ value: mrr })
render json: serialize_model(stat)
end
end
app/urls.py
from django.urls import path
from django.views.decorators.csrf import csrf_exempt
from . import views
app_name = 'app'
urlpatterns = [
path('/stats/mrr', csrf_exempt(views.ChartsMrrView.as_view()), name='stats-mrr')
]
app/views.py
import uuid
import stripe
from datetime import datetime
import pytz
from django.views import generic
from django.http import JsonResponse
class ChartsMrrView(generic.ListView):
def post(self, request, *args, **kwargs):
mrr = 0
from_ = int(datetime(2018, 3, 1, 0, 0, 0, 0, tzinfo=pytz.UTC).timestamp())
to_ = int(datetime(2018, 3, 31, 0, 0, 0, 0, tzinfo=pytz.UTC).timestamp())
stripe.api_key = os.getenv('STRIPE_SECRET_KEY')
response = stripe.Charge.list(
limit=100,
created={'gte': from_, 'lte': to_}
)
for charge in response['data']:
mrr += charge['amount']
res = {
'data': {
'attributes': {
'value': {
'countCurrent': mrr
}
},
'type': 'stats',
'id': uuid.uuid4()
}}
return JsonResponse(res, safe=False)
app/Http/Controllers/ChartsController.php
<?php
namespace App\Http\Controllers;
use ForestAdmin\LaravelForestAdmin\Facades\ChartApi;
use Stripe\StripeClient;
class ChartsController extends Controller
{
public function mrr()
{
$mrr = 0;
$stripe = new StripeClient('sk_AABBCCDD11223344');
$charges = $stripe->charges->all(['limit' => 3]);
foreach ($charges as $charge) {
$mrr += $charge->amount;
}
return ChartApi::renderValue($mrr);
}
}
routes/web.php
<?php
use App\Http\Controllers\ChartsController;
use Illuminate\Support\Facades\Route;
Route::post('forest/stats/mrr', [ChartsController::class, 'mrr']);
app/Http/Middleware/VerifyCsrfToken.php
<?php
namespace App\Http\Middleware;
use Illuminate\Foundation\Http\Middleware\VerifyCsrfToken as Middleware;
class VerifyCsrfToken extends Middleware
{
/**
* The URIs that should be excluded from CSRF verification.
*
* @var array<int, string>
*/
protected $except = [
'forest/stats/mrr',
];
}

Repartition API-based Chart

On our Live Demo, we have a Charges repartition chart which shows a repartition chart distributed by credit card country. This chart queries the Stripe API to get all charges made in the current month (in March for this example) and check the credit card country.
SQL
Mongodb
Rails
Django
Laravel
When serializing the data, we use the Liana.StatSerializer() serializer. Check the value syntax below.
{
value: [{
key: <string> ,
value: <number>
}, {
key: <string> ,
value: <number>
}, …]
}
/routes/dashboard.js
const _ = require('lodash');
const P = require('bluebird');
const express = require('express');
const router = express.Router();
const Liana = require('forest-express-sequelize');
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
const moment = require('moment');
router.post('/stats/credit-card-country-repartition', Liana.ensureAuthenticated, (req, res) => {
let repartition = [];
let from = moment.utc('2018-03-01').unix();
let to = moment.utc('2018-03-20').unix();
return stripe.charges
.list({
created: { gte: from, lte: to }
})
.then((response) => {
return P.each(response.data, (charge) => {
let country = charge.source.country || 'Others';
let entry = _.find(repartition, { key: country });
if (!entry) {
repartition.push({ key: country, value: 1 });
} else {
entry.value++;
}
});
})
.then(() => {
let json = new Liana.StatSerializer({
value: repartition
}).perform();
res.send(json);
});
});
module.exports = router;
When serializing the data, we use the Liana.StatSerializer() serializer. Check the value syntax below.
{
value: [{
key: <string> ,
value: <number>
}, {
key: <string> ,
value: <number>
}, …]
}
/routes/dashboard.js
const _ = require('lodash');
const P = require('bluebird');
const express = require('express');
const router = express.Router();
const Liana = require('forest-express-mongoose');
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
const moment = require('moment');
router.post('/stats/credit-card-country-repartition', Liana.ensureAuthenticated, (req, res) => {
let repartition = [];
let from = moment.utc('2018-03-01').unix();
let to = moment.utc('2018-03-20').unix();
return stripe.charges
.list({
created: { gte: from, lte: to }
})
.then((response) => {
return P.each(response.data, (charge) => {
console.log(charge.source);
let country = charge.source.country || 'Others';
let entry = _.find(repartition, { key: country });
if (!entry) {
repartition.push({ key: country, value: 1 });
} else {
entry.value++;
}
});
})
.then(() => {
let json = new Liana.StatSerializer({
value: repartition
}).perform();
res.send(json);
});
});
module.exports = router;
When serializing the data, we use the serialize_model() method. Check the value syntax below.
{
value: [{
key: <string> ,
value: <number>
}, {
key: <string> ,
value: <number>
}, …]
}
/config/routes.rb
Rails.application.routes.draw do
# MUST be declared before the mount ForestLiana::Engine.
namespace :forest do
post '/stats/credit-card-country-repartition' => 'charts#credit_card_country_repartition'
end
mount ForestLiana::Engine => '/forest'
end
class Forest::ChartsController < ForestLiana::ApplicationController
def credit_card_country_repartition
repartition = []
from = Date.parse('2018-03-01').to_time(:utc).to_i
to = Date.parse('2018-03-20').to_time(:utc).to_i
Stripe::Charge.list({
created: { gte: from, lte: to },
limit: 100
}).each do |charge|
country = charge.source.country || 'Others'
entry = repartition.find { |e| e[:key] == country }
if !entry
repartition << { key: country, value: 1 }
else
++entry[:value]
end
end
stat = ForestLiana::Model::Stat.new({ value: repartition })
render json: serialize_model(stat)
end
end
app/urls.py
from django.urls import path
from django.views.decorators.csrf import csrf_exempt
from . import views
app_name = 'app'
urlpatterns = [
path('/stats/credit-card-country-repartition', csrf_exempt(views.CreditCardCountryRepartitionView.as_view()), name='stats-credit-card-country-repartition')
]
app/views.py
import uuid
import stripe
from datetime import datetime
import pytz
from django.views import generic
from django.http import JsonResponse
class CreditCardCountryRepartitionView(generic.ListView):
def post(self, request, *args, **kwargs):
repartition = [];
from_ = int(datetime(2018, 3, 1, 0, 0, 0, 0, tzinfo=pytz.UTC).timestamp())
to_ = int(datetime(2018, 3, 31, 0, 0, 0, 0, tzinfo=pytz.UTC).timestamp())
stripe.api_key = os.getenv('STRIPE_SECRET_KEY')
response = stripe.Charge.list(
created={'gte': from_, 'lte': to_}
)
for charge in response['data']:
country = charge['source']['country'] or 'Others'
entry = next((x for x in repartition if x['key'] == country), None)
if entry is None:
repartition.append({'key': country, 'value': 1})
else:
entry['value'] += 1
res = {
'data': {
'attributes': {
'value': repartition,
},
'type': 'stats',
'id': uuid.uuid4()
}}
return JsonResponse(res, safe=False)
{
value: [{
key: <string> ,
value: <number>
}, {
key: <string> ,
value: <number>
}, …]
}
app/Http/Controllers/ChartsController.php
<?php
namespace App\Http\Controllers;
use ForestAdmin\LaravelForestAdmin\Facades\ChartApi;
use Stripe\StripeClient;
class ChartsController extends Controller
{
public function creditCardCountryRepartition()
{
$repartition = [];
$from = new \DateTime('2022-01-01');
$to = new \DateTime('2022-04-04');
$stripe = new StripeClient('sk_AABBCCDD11223344');
$charges = $stripe->charges->all(
[
'created' => [
'gte' => $from->getTimestamp(),
'lte' => $to->getTimestamp(),
],
'limit' => 100,
]
);
foreach ($charges as $charge) {
$country = $charge->source?->country ?: 'Others';
if (!isset($repartition[$country])) {
$repartition[$country] = ['key' => $country, 'value' => 1];
} else {
$repartition[$country]['value']++;
}
}
return ChartApi::renderPie(array_values($repartition));
}
}
routes/web.php
<?php
use App\Http\Controllers\ChartsController;
use Illuminate\Support\Facades\Route;
Route::post('forest/stats/credit-card-country-repartition', [ChartsController::class, 'creditCardCountryRepartition']);
app/Http/Middleware/VerifyCsrfToken.php
<?php
namespace App\Http\Middleware;
use Illuminate\Foundation\Http\Middleware\VerifyCsrfToken as Middleware;
class VerifyCsrfToken extends Middleware
{
/**
* The URIs that should be excluded from CSRF verification.
*
* @var array<int, string>
*/
protected $except = [
'forest/stats/credit-card-country-repartition',
];
}

Time-based API-based Chart

On our Live Demo, we have a Charges time-based chart which shows the number of charges per day. This chart queries the Stripe API to get all charges made in the current month (in March for this example) and group data by day.
SQL
Mongodb
Rails
Django
Laravel
When serializing the data, we use the Liana.StatSerializer() serializer. Check the value syntax below.
{
value: [{
label: <string> ,
values: { value: <number> }
}, {
label: <string> ,
values: { value: <number> }
}, …]
}
/routes/dashboard.js
const _ = require('lodash');
const P = require('bluebird');
const express = require('express');
const router = express.Router();
const Liana = require('forest-express-sequelize');
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
const moment = require('moment');
router.post('/stats/charges-per-day', (req, res) => {
let values = [];
let from = moment.utc('2018-03-01').unix();
let to = moment.utc('2018-03-31').unix();
return stripe.charges
.list({
created: { gte: from, lte: to }
})
.then((response) => {
return P.each(response.data, (charge) => {
let date = moment.unix(charge.created).startOf('day').format('LLL');
let entry = _.find(values, { label: date });
if (!entry) {
values.push({ label: date, values: { value: 1 } });
} else {
entry.values.value++;
}
});
})
.then(() => {
let json = new Liana.StatSerializer({
value: values
}).perform();
res.send(json);
});
});
module.exports = router;
When serializing the data, we use the Liana.StatSerializer() serializer. Check the value syntax below.
{
value: [{
label: <string> ,
values: { value: <number> }
}, {
label: <string> ,
values: { value: <number> }
}, …]
}
/routes/dashboard.js
const _ = require('lodash');
const P = require('bluebird');
const express = require('express');
const router = express.Router();
const Liana = require('forest-express-mongoose');
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
const moment = require('moment');
router.post('/stats/charges-per-day', (req, res) => {
let values = [];
let from = moment.utc('2018-03-01').unix();
let to = moment.utc('2018-03-31').unix();
return stripe.charges
.list({
created: { gte: from, lte: to }
})
.then((response) => {
return P.each(response.data, (charge) => {
let date = moment.unix(charge.created).startOf('day').format('LLL');
let entry = _.find(values, { label: date });
if (!entry) {
values.push({ label: date, values: { value: 1 } });
} else {
entry.values.value++;
}
});
})
.then(() => {
let json = new Liana.StatSerializer({
value: values
}).perform();
res.send(json);
});
});
module.exports = router;
When serializing the data, we use the serialize_model() method. Check the value syntax below.
{
value: [{
label: <string> ,
values: { value: <number> }
}, {
label: <string> ,
values: { value: <number> }
}, …]
}
/config/routes.rb
Rails.application.routes.draw do
# MUST be declared before the mount ForestLiana::Engine.
namespace :forest do
post '/stats/charges-per-day' => 'charts#charges_per_day'
end
mount ForestLiana::Engine => '/forest'
end
/app/controllers/forest/charts_controller.rb
class Forest::ChartsController < ForestLiana::ApplicationController
def charges_per_day
values = []
from = Date.parse('2018-03-01').to_time(:utc).to_i
to = Date.parse('2018-03-31').to_time(:utc).to_i
Stripe::Charge.list({
created: { gte: from, lte: to },
limit: 100
}).each do |charge|
date = Time.at(charge.created).beginning_of_day.strftime("%d/%m/%Y")
entry = values.find { |e| e[:label] == date }
if !entry
values << { label: date, values: { value: 1 } }
else
++entry[:values][:value]
end
end
stat = ForestLiana::Model::Stat.new({ value: values })
render json: serialize_model(stat)
end
end
app/urls.py
from django.urls import path
from django.views.decorators.csrf import csrf_exempt
from . import views
app_name = 'app'
urlpatterns = [
path('/stats/charges-per-day', csrf_exempt(views.ChargesPerDayView.as_view()), name='stats-charges-per-day')
]
app/views.py
import uuid
import stripe
from datetime import datetime
import pytz
from django.views import generic
from django.http import JsonResponse
class ChargesPerDayView(generic.ListView):
def post(self, request, *args, **kwargs):
values = [];
from_ = int(datetime(2018, 3, 1, 0, 0, 0, 0, tzinfo=pytz.UTC).timestamp())
to_ = int(datetime(2018, 3, 31, 0, 0, 0, 0, tzinfo=pytz.UTC).timestamp())
stripe.api_key = os.getenv('STRIPE_SECRET_KEY')
response = stripe.Charge.list(
created={'gte': from_, 'lte': to_}
)
for charge in response['data']:
date = datetime.fromtimestamp(charge['created']).replace(hour=0, minute=0, second=0, microsecond=0)
entry = next((x for x in repartition if x['label'] == date), None)
if entry is None:
values.append({'label': date, 'values': {'value': 1}]})
else:
entry['values']['value'] += 1
res = {
'data': {
'attributes': {
'value': values,
},
'type': 'stats',
'id': uuid.uuid4()
}}
return JsonResponse(res, safe=False)
{
value: [{
label: <string> ,
values: { value: <number> }
}, {
label: <string> ,
values: { value: <number> }
}, …]
}
app/Http/Controllers/ChartsController.php
<?php
namespace App\Http\Controllers;
use Faker\Factory;
use ForestAdmin\LaravelForestAdmin\Facades\ChartApi;
use Stripe\StripeClient;
class ChartsController extends Controller
{
public function chargesPerDay()
{
$values = [];
$from = new \DateTime('2022-01-01');
$to = new \DateTime('2022-02-01');
$stripe = new StripeClient('sk_AABBCCDD11223344');
$charges = $stripe->charges->all(
[
'created' => [
'gte' => $from->getTimestamp(),
'lte' => $to->getTimestamp(),
],
'limit' => 100,
]
);
foreach ($charges as $charge) {
$date = \