https://github.com/aldaviva/freshbadge
🛡 Convert a Freshping uptime Check into a Shields.io Badge
https://github.com/aldaviva/freshbadge
freshping shields-io shieldsio shieldsio-badges shieldsio-endpoint uptime
Last synced: 6 months ago
JSON representation
🛡 Convert a Freshping uptime Check into a Shields.io Badge
- Host: GitHub
- URL: https://github.com/aldaviva/freshbadge
- Owner: Aldaviva
- License: apache-2.0
- Created: 2025-01-17T12:24:24.000Z (9 months ago)
- Default Branch: master
- Last Pushed: 2025-03-03T19:43:09.000Z (7 months ago)
- Last Synced: 2025-03-27T04:34:47.153Z (7 months ago)
- Topics: freshping, shields-io, shieldsio, shieldsio-badges, shieldsio-endpoint, uptime
- Language: C#
- Homepage:
- Size: 47.9 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: Readme.md
- License: License.txt
Awesome Lists containing this project
README
FreshBadge
===
[](https://statuspage.freshping.io/61473-Aldaviva)
Create a [Shields.io](https://shields.io) Badge for a [Freshping](https://freshping.io/) uptime Check, like the one above.
This is a free alternative to the [official Freshping badges](https://support.freshping.io/support/solutions/articles/50000002949-what-is-a-status-badge-), which are theoretically available after reviewing Freshping and [filling out a support request/survey](https://support.freshping.io/support/tickets/new). It's also pretty and uniform looking because it uses Shields.io instead of some ugly one-off design.
- [Setup](#setup)
1. [Freshping](#freshping)
1. [Self-hosted FreshBadge server \(optional\)](#self-hosted-freshbadge-server-optional)
1. [Shields.io](#shieldsio)
- [API](#api)
## Setup
### Freshping
1. Log in to your existing [Freshping account](https://login.freshworks.com/email-login).
- â›” [Freshworks disabled the ability to sign up for new Freshping accounts](https://support.freshping.io/en/support/solutions/articles/50000006524-suspension-of-new-signups-faqs) in 2023, so if you don't already have an account, you can't create one anymore.
1. Go to your Freshping Dashboard.
1. Decide which Check you want to appear in your Badge, and go to its Report page.
1. From the Report page URL, copy the Check ID number from the `check_id` query parameter.
1. Add the Check to a Status Page.
- If this Check is already in at least one Status Page, you can skip this step.
- If there are no Status Pages in your Freshping account, first create a new Status Page.
- This step is necessary to allow the Check's status and uptime to be accessed through Freshping's API.
### Self-hosted FreshBadge server (optional)
If you want to use my hosted FreshBadge server instance, skip to the [Shields.io](#shieldsio) steps. Otherwise, you can run a FreshBadge server yourself.
1. Download the [latest release](https://github.com/Aldaviva/FreshBadge/releases/latest) for your operating system and CPU.
1. Extract the ZIP file to a directory on your computer.
#### IIS
1. Ensure the Web Server (IIS) role (`Web-Server`) is installed.
1. Ensure the [ASP.NET Core Hosting Bundle 8 or later](https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/iis/hosting-bundle) is installed.
1. Log in to your server using IIS Manager.
1. In Application Pools, create a new Application Pool (CLR 4).
- Don't use `DefaultAppPool` or any other non-empty pools, because ASP.NET Core webapps must each run isolated in their own pool.
1. In your Site, add a new Application (View Applications › Add Application).
- The Alias is the URL path prefix (context root) of the app that should appear in the base URL, such as `freshbadge`.
- Choose the Application Pool you created above.
- Set the Physical Path to the directory you extracted the FreshBadge release into, which contains `FreshBadge.dll`.
#### Kestrel
1. [Configure](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel/endpoints) listening ports, TLS certificates, and other settings in `appsettings.json`.
1. Execute the `FreshBadge` program.
### Shields.io
#### Badge JSON URL
```url
https://west.aldaviva.com/freshbadge/{checkId}
```
where `{checkId}` is the ID of the Freshping Check you want to monitor, for example,
```url
https://west.aldaviva.com/freshbadge/304333
```
- For self-hosted FreshBadge instances, replace the base URL `https://west.aldaviva.com/freshbadge/` with your own server's base URL.
- See the [API documentation](#api) for additional parameters that can customize the Badge.
#### Badge SVG URL
```url
https://img.shields.io/endpoint?url={badgeJson}
```
for example
```url
https://img.shields.io/endpoint?url=https%3A%2F%2Fwest.aldaviva.com%2Ffreshbadge%2F304333
```
- Like all URI path segments, the `{badgeJson}` parameter value must be [URI-encoded](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent).
- The right side of the Badge's background color is green when the uptime is at least 99.5%, transitioning to orange as the uptime decreases in the Fibonacchi sequence to 91%. When the uptime is lower or the check is down, the background color is red.
- You can customize the Badge appearance using the [Endpoint Badge query parameters](https://shields.io/badges/endpoint-badge#:~:text=the%20query%20string.-,Query%20Parameters,-url%20string%20%E2%80%94):
```url
https://img.shields.io/endpoint?url=https%3A%2F%2Fwest.aldaviva.com%2Ffreshbadge%2F304333&label=uptime+(90+days)&color=informational
```
#### SVG image in Markdown
```markdown
```
#### Link to Status Page in Markdown
```markdown
[](https://statuspage.freshping.io/61473-Aldaviva)
```
[](https://statuspage.freshping.io/61473-Aldaviva)
## API
- URL template: `https://west.aldaviva.com/freshbadge/{checkId}{?period,precision,locale}`
- Verb: `GET`
- Parameters
- `checkId`
- **importance:** required
- **location:** path
- **type:** number (64-bit signed integer)
- **meaning:** numeric ID of the Freshping Check to show uptime for, as seen in the `check_id` query parameter of the Freshping report page for this Check (`/reports?check_id={checkId}`)
- `period`
- **importance:** optional
- **location:** query
- **type:** string
- **format:** [ISO 8601 time period](https://en.wikipedia.org/wiki/ISO_8601#Durations)
- **meaning:** period over which to calculate the Check's uptime percentage, ending at the current time
- **range:** [1 minute, 90 days]
- **default:** 90 days
- **example:** `?period=P30D` (30 days) 
- `precision`
- **importance:** optional
- **location:** query
- **type:** number (8-bit unsigned integer)
- **meaning:** how many digits after the decimal point the uptime percentage should show
- **range:** [0, 256)
- **default:** 4 (the finest Freshping check granularity is 1 minute, and the longest data retention is 90 days, which means 4 digits after the decimal point will always be precise enough to express even the shortest outage)
- **example:** `?precision=2` (2 digits after the decimal point) 
- `locale`
- **importance:** optional
- **location:** query
- **type:** string
- **format:** [IETF BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag)
- **meaning:** locale to use when rendering the uptime label and percentage
- **range:** any language tag supported by [Windows](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c) or [ICU](https://icu.unicode.org/) (on *nix); the "uptime" label is currently badly localized in `de`, `es`, `fr`, and `it`.
- **default:** `en-US` (US English), or the server user's locale when self-hosted
- **example:** `?locale=fr` (France format) 
- Response body: JSON object that conforms to the [Shields.io JSON Endpoint schema](https://shields.io/badges/endpoint-badge#:~:text=Example%20Shields%20Response-,Schema,-Property)
```json
{
"schemaVersion": 1,
"label": "uptime",
"message": "99.9133%",
"color": "brightgreen",
"isError": false,
"logoSvg": ""
}
```