IP Badge
Below are several of the most common ways to embed the badge on a webpage: showing only the IP, showing the country code, showing the country name in Chinese, querying a specific IP, and “status-style” badges with colors. Each method is displayed in a single line, making it ideal for personal homepages, admin dashboards, announcement pages, or status pages.
Your current IP address:
Detect egress location (code):
(e.g., US/TW/JP)
Detect egress location (Chinese):
Query a specific IP (8.8.8.8):
Query a specific IP (Chinese):
Status-style display (blue):
(You can also use hex: /check-ip-zh-ff0000)
Shows only the visitor’s IP (single-segment badge) for the cleanest output; great for quickly displaying your current egress IP in a README or status page.
<img src="https://s.ipin.io/myip" alt="My IP" />Append -blue/-green/-gray and similar tokens at the end of the route to control the background color, making the badge match your page theme.
<img src="https://s.ipin.io/myip-gray" alt="My IP (gray)" />Supports 6-digit hexadecimal colors (without #) for precise matching with brand or theme colors.
<img src="https://s.ipin.io/myip-111827" alt="My IP (custom color)" />Shows the visitor’s IP plus the country code country_code (e.g., US/TW/JP), ideal for dashboards and status pages to quickly identify the egress location.
<img src="https://s.ipin.io/check-ip" alt="IP + country code" />Append -blue/-green and similar tokens to change the color of the right-side result block—commonly used for “status semantics” displays.
<img src="https://s.ipin.io/check-ip-blue" alt="IP + country code (blue)" />Use a 6-digit hex value to customize the color of the right-side result block—great for matching theme colors or color-coding by risk level.
<img src="https://s.ipin.io/check-ip-16a34a" alt="IP + country code (custom green)" />Queries and displays the country code for a specified IP—handy for visualizing “suspicious IPs” in tickets, alerts, or log analysis.
<img src="https://s.ipin.io/check-8.8.8.8" alt="8.8.8.8 + country code" />Add a color suffix to a specified IP to “colorize” risk levels (e.g., red = high risk, yellow = needs attention).
<img src="https://s.ipin.io/check-8.8.8.8-red" alt="8.8.8.8 (red)" />When the route includes a language segment such as -zh/-en/-ja, the right side shows “code + country name”. Without a language segment, the country name is not included by default.
<img src="https://s.ipin.io/check-ip-zh" alt="IP + code + country name (Chinese)" />Language and color segments can be combined: /check-ip-zh-blue. Common color tokens include: sky cyan green emerald yellow orange red rose gray black
<img src="https://s.ipin.io/check-ip-zh-blue" alt="Chinese country name (blue)" />Query a specified IP and output the country name in the chosen language—ideal for embedding “alert IPs” into tickets or notifications so readers can quickly understand the source country without opening details.
<img src="https://s.ipin.io/check-8.8.8.8-zh" alt="8.8.8.8 + country name (Chinese)" />A three-part combination of specified IP + language + color is best for visualizing “security/risk levels”: for example, red indicates high risk, while green indicates a whitelist.
<img src="https://s.ipin.io/check-8.8.8.8-zh-green" alt="8.8.8.8 (Chinese + green)" />IP Badge Tool Overview
IP Badge is a lightweight “image API” that takes the visitor’s IP (or an IP you specify) along with the corresponding
country_code (country code) and
country_name (country name, optional),
renders them into an embeddable SVG badge image, and returns it with
Content-Type: image/svg+xml.
Unlike traditional lookup APIs that return JSON, an SVG badge can be displayed like a normal image in a README, admin dashboard, monitoring wall, status page, or anywhere that supports an
<img>
tag—without any extra front-end rendering.
The tool uses a two-segment badge layout (similar to shields.io): the left side typically shows the IP, and the right side shows the lookup result (country code or “code + country name”). It also supports controlling colors and languages via route segments.
For data sources, IP geolocation uses the local table
ip2location_db11
(matching IPv4 ranges to obtain country_code),
and multilingual country names come from
sys_lang_multi,
mapping by vc_code to fields like
name_en / name_zh / name_ja ...
(the country name is output only when the route includes a language segment).
The tool also attempts to extract the real client IP from common proxy headers (e.g., Cloudflare, X-Forwarded-For), which makes it suitable for deployments behind a CDN, reverse proxy, or load balancer.
Routes and Output: From Minimal to Full
The core idea of IP Badge is: use the route as an image URL. Opening the route directly in a browser shows the SVG badge,
and referencing the same URL in Markdown or HTML renders it as an image. To support different “information density” needs, there are two main route groups: myip and check:
myip is for display (IP only), while check is for lookup (with country info).
Also, the country name is shown only when the route includes -<lang>;
without a language segment, only the country code is displayed to keep the output shorter and more badge-like.
GET /myipUse cases: showing the current server egress IP, verifying whether proxy chains forward the real IP, personal homepage display, etc. The output is a single-segment badge containing only the IP text.
GET /check-ip
Use cases: monitoring dashboards and status pages for quickly indicating the “egress country”. The right side shows only country_code (e.g., US / TW / JP).
GET /check-8.8.8.8Use cases: turning “suspicious IPs” into visual tags in tickets, alerts, or log analysis, making it easy to identify the source country at a glance.
GET /check-ip-zh
Use cases: pages for non-technical users or where higher readability is needed; the right side shows country_code + country_name, e.g., “US United States”.
When the language is omitted, the country name is not output by default to avoid overly long badges.
GET /check-8.8.8.8-zhUse cases: security operations, overseas troubleshooting, customer support ticketing systems, etc.—embed country info for an IP as an “image badge” into any page or message body.
Color Control (Option B): Append -<color> Like shields
IP Badge lets you append -<color> at the end of a route to control the badge background color (typically the right-side result area),
matching the shields.io experience: you can use simple color tokens (such as blue/green/red/gray), or a 6-digit hex color value (without #).
This lets you bind colors to business meaning—for example, “green = normal, yellow = needs attention, red = high risk”—so the badge conveys both information and status semantics.
-
Use a color token:
GET /check-ip-zh-blue GET /check-8.8.8.8-greenTokens are great for quick color selection, such as blue/green/red/orange/yellow/gray, etc. (based on the mapping table in your controller).
-
Use a 6-digit hex value (without #):
GET /check-ip-zh-ff0000 GET /check-8.8.8.8-16a34aHex values are best when you need strict alignment with your site theme color—for example, your admin system primary color or brand palette—for a consistent UI.
-
myip can also take colors:
GET /myip-gray GET /myip-111827Single-segment badges are often used for “display”; adding colors can help them blend with the page style or stand out in lists.
Embedding: Works Directly in Markdown / HTML / Dashboards
Because IP Badge outputs an SVG image, the recommended approach is to embed it directly. In GitHub/GitLab README files or wikis, use Markdown image syntax;
on any webpage or admin panel, reference it with an <img> tag.
The biggest benefit is that you don’t need extra front-end logic, and you don’t have to handle CORS JSON, templates, or typography—browsers can render SVGs as images natively.
<img src="https://s.ipin.io/check-8.8.8.8-zh-green" alt="IP Badge" />If you plan to display many badges on a large screen or status page (e.g., multiple node egresses, multiple IP intel items), consider enabling a longer cache duration (e.g., 1 hour or more). This can significantly reduce DB lookup pressure and improve load speed. Since IP geolocation changes infrequently, caching provides substantial benefits.
Common Use Cases: Turn “IP Info” into a Visual Component
IP Badge is ideal for display-oriented needs. For example, on an ops status page you can turn each node’s egress IP/country info into a “badge wall” to instantly spot whether a node is exiting from an unexpected region;
in security operations, you can embed alert IPs as red badges into tickets or notifications (e.g., “US United States” / “RU Russia”), so on-call staff can understand the risk context without opening details;
when debugging CDN/reverse-proxy chains, visiting /myip and /check-ip
helps you quickly verify whether the real client IP is being forwarded correctly or overwritten;
in multilingual back offices or international SaaS products, using -zh/-en/-ja
allows the same IP to show different country names across language UIs, reducing the need to maintain front-end localization dictionaries.
Going further, you can bind colors to business status—for example, green for “allowed”, yellow for “verification needed”, and red for “blocked/high risk”—so the badge carries both “info + status”.
Tip: If you plan to expose this to the public internet, consider enforcing a “trusted proxy headers” policy at the reverse-proxy or application layer to prevent clients from spoofing headers like X-Forwarded-For and causing incorrect displays.
Also consider adding indexes on
ip2location_db11.ip_from and
sys_lang_multi.vc_code,
and use cache headers to improve performance and stability.
