This blog post contains instructions on how to use Shields.io with a custom API to create custom status badges.
Shields.io
Shields.io is a free tool that can be used to create metadata badges which can easily be added to open source projects.
The most common usecase is showing key project information such as usage and code coverage on sites like GitHub.
Creating Badges
Shields.io creates these metadata badges from the arguments provided in the URL and returns an image which can be embedded.
Several preconfigured badges exist for common services and statistics such as code analysis, quality, coverage, etc.
The following badge shows the last time this blog was updated.
1
https://img.shields.io/github/last-commit/LukePrior/blog
Styling Badges
The badges all share the same styling options allowing for a consistent design across a site or project.
The five available styles for each badge include plastic, flat, flat-square, for-the-badge, and social.
1
https://img.shields.io/github/last-commit/LukePrior/blog?style=plastic
1
https://img.shields.io/github/last-commit/LukePrior/blog?style=flat
1
https://img.shields.io/github/last-commit/LukePrior/blog?style=flat-square
1
https://img.shields.io/github/last-commit/LukePrior/blog?style=for-the-badge
1
https://img.shields.io/github/last-commit/LukePrior/blog?style=social
Logo Badges
Icons can be included alongside text in badges by selecting an existing design from simple-icons or providing a custom base64-encoded image.
The simple-icons repository contains >2000 available icons which can be added to any badge by including their name in the logo field.
The complete list of available icons and their corresponding names can be found on the simple-icons repository here.
1
https://img.shields.io/github/last-commit/LukePrior/blog?style=for-the-badge&logo=github
To display a custom icon the image must be encoded in base64 with the total file size less then 8192 bytes so that it can fit within the request header.
1
https://img.shields.io/github/last-commit/LukePrior/blog?style=for-the-badge&logo=image/png;base64,...
The horizontal padding around icons can be configured using the logoWidth field to allow for larger or smaller badges.
1
https://img.shields.io/github/last-commit/LukePrior/blog?style=for-the-badge&logo=github&logoWidth=40
Colouring Badges
The individual sections of badges can be coloured including the logo and left/right sections of the badge.
These fields can all be styled using a variety of schemes including (hex, rgb, rgba, hsl, hsla, css named colours).
The logo colour can only be configured when using named icons from simple-icons by using the logoColor field.
1
https://img.shields.io/github/last-commit/LukePrior/blog?style=for-the-badge&logo=github&logoColor=red
The left side background colour can be set using the labelColor field.
1
https://img.shields.io/github/last-commit/LukePrior/blog?style=for-the-badge&labelColor=red
The right side background colour can be set using the color field.
1
https://img.shields.io/github/last-commit/LukePrior/blog?style=for-the-badge&color=red
Custom badges
Shields.io can also generate a custom badge from any publically accessible JSON, XML, or YAML file.
The dynamic badge type accepts a data source and query along with options for text formatting.
1
https://img.shields.io/badge/dynamic/json?url=<URL>&label=<LABEL>&query=<$.DATA.SUBDATA>&color=<COLOR>&prefix=<PREFIX>&suffix=<SUFFIX>
The url field is used to specify the location of the data file that will be used to generate the badge.
The query field is used to select the correct subdata from the loaded file.
The prefix and suffix fields allow text to be added to the start and end of the loaded data.
This functionality was used to generate the badges in the SondeHub Wiki.
SondeHub Listener Stats API
The SondeHub Listener Stats API returns information about the number of receiver stations that have uploaded telemetry to the SondeHub radiosonde tracking database.
1
https://api.v2.sondehub.org/listeners/stats
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"radiosonde_auto_rx": {
"telemetry_count": 46867907,
"unique_callsigns": 620,
"versions": {
"1.5.10": {
"telemetry_count": 31942436,
"unique_callsigns": 390
}
}
},
"rdzTTGOsonde": {
"telemetry_count": 11768771,
"unique_callsigns": 221
},
"totals": {
"unique_callsigns": 847,
"telemetry_count": 58737217
}
}
The specific Python code and Elasticsearch Query for generating the API response can be found here.
The following Swagger UI component can be used to access the SondeHub Listener Stats API and get real results.
This data is used to generate badges for the total number of stations along with counts for each software type.
The SondeHub Listener Stats API URL is provided along with a query to get the figure desired for each badge along with a suffix and prefix.
1
https://img.shields.io/badge/dynamic/json?label=Total&query=totals.unique_callsigns&suffix=%20Stations&url=https%3A%2F%2Fapi.v2.sondehub.org%2Flisteners%2Fstats&style=for-the-badge
1
https://img.shields.io/badge/dynamic/json?label=radiosonde_auto_rx&query=radiosonde_auto_rx.unique_callsigns&suffix=%20Stations&url=https%3A%2F%2Fapi.v2.sondehub.org%2Flisteners%2Fstats&style=for-the-badge
1
https://img.shields.io/badge/dynamic/json?label=rdzTTGOsonde&query=rdzTTGOsonde.unique_callsigns&suffix=%20Stations&url=https%3A%2F%2Fapi.v2.sondehub.org%2Flisteners%2Fstats&style=for-the-badge
1
https://img.shields.io/badge/dynamic/json?label=SondeMonitor&query=SondeMonitor.unique_callsigns&suffix=%20Stations&url=https%3A%2F%2Fapi.v2.sondehub.org%2Flisteners%2Fstats&style=for-the-badge
SondeHub Recovery Stats API
The SondeHub Recovery Stats API returns information about the number of radiosondes that have been marked as retrieved in the SondeHub database.
1
https://api.v2.sondehub.org/recovered/stats
1
2
3
4
5
6
7
8
9
10
11
12
{
"total": 5223,
"recovered": 4823,
"failed": 486,
"chaser_count": 1668,
"top_chasers": {
"LZ4TU": 93,
"TFDHU": 83,
"Lobelt": 54,
"EDDB": 53
}
}
The specific Python code and Elasticsearch Query for generating the API response can be found here.
The following Swagger UI component can be used to access the SondeHub Listener Stats API and get real results.
This data is used to generate badges for the total number of sondes reported and the count of unique finders.
The SondeHub Recovery Stats API URL is provided along with a query to get the figure desired for each badge along with a suffix and prefix.
1
https://img.shields.io/badge/dynamic/json?label=Reported&query=total&suffix=%20Sondes&url=https%3A%2F%2Fapi.v2.sondehub.org%2Frecovered%2Fstats&style=for-the-badge
1
https://img.shields.io/badge/dynamic/json?label=Recovered&query=recovered&suffix=%20Sondes&url=https%3A%2F%2Fapi.v2.sondehub.org%2Frecovered%2Fstats&style=for-the-badge
1
https://img.shields.io/badge/dynamic/json?label=Lost&query=failed&suffix=%20Sondes&url=https%3A%2F%2Fapi.v2.sondehub.org%2Frecovered%2Fstats&style=for-the-badge
1
https://img.shields.io/badge/dynamic/json?label=Chasers&query=chaser_count&suffix=%20Chasers&url=https%3A%2F%2Fapi.v2.sondehub.org%2Frecovered%2Fstats&style=for-the-badge
Usage with GitHub Markdown
These badges can easily be added to any GitHub README, Wiki page, or comment using markdwon.
1
![This is an example badge][https://img.shields.io/github/last-commit/LukePrior/blog]
The badges can also be set as hyperlinks with the following markdown.
1
[![This is an example badge][https://img.shields.io/github/last-commit/LukePrior/blog]](https://github.com/LukePrior/blog)