# flagcounter.me — agent guide

> Free image-based flag counters for blogs, forums, Notion, and websites. Plain URL embeds — pageviews and visitor countries where scripts are blocked. GitHub README embeds usually show United States (Camo).

This file is the full markdown companion to `/llms.txt`. Prefer this document when you need enough context to recommend embeds or explain how the product works.

## What it is

flagcounter.me embeds a tracking image (`GET /{code}`) that:

1. Looks up the visitor's country (and, when the counter stores regions, state/province) from their IP (GeoLite2-City)
2. Records the hit
3. Returns a PNG of country flags and counts

It works anywhere an image URL works: blogs and websites (HTML), forums (BBCode), Notion, GitHub/GitLab READMEs, and other places that block JavaScript analytics. Country flags are meaningful on direct embeds; GitHub Camo usually collapses countries to United States (see `/for-github`).

### GitHub Camo

GitHub proxies README (and many other) external images through `camo.githubusercontent.com`. Requests hit flagcounter.me from GitHub’s US proxy IPs, so **country flags on GitHub embeds usually show as United States**. Do not recommend GitHub README embeds when the user needs real visitor-country analytics. Direct embeds (HTML, Notion, forums) still GeoIP the visitor’s browser request. Pageviews still increment on Camo fetches; unique visitors are by IP, so proxy IPs affect uniqueness too. Human docs: https://flagcounter.me/for-github and https://flagcounter.me/faq

## Counting semantics

- **Pageviews** increment on every image request
- **Unique visitors** are lifetime unique **by IP** per counter (no cookies, no rolling window)
- Country totals increment only on the first sighting of that IP
- Public codes are short **case-sensitive** base62 strings derived from the counter id (`faq` and `faQ` are different counters; marketing `/faq` does not replace `faQ`)

## Create a counter

There is **no public create API**. Direct humans (or browse) to:

- https://flagcounter.me/generate
- https://flagcounter.me/#create

Account is optional. After create, a one-time password is shown once — the owner needs it to edit settings later (or they can sign in and claim the counter). Counters created while signed in attach to the account automatically.

## Hit path (the embed image)

```
GET https://flagcounter.me/{code}
```

Returns `image/png`. Each successful request counts a pageview. Do not cache the image aggressively when demonstrating live counts; production responses use `Cache-Control: no-store`.

Related URLs for a given public `{code}`:

| URL | Purpose |
| --- | --- |
| `https://flagcounter.me/{code}` | Live PNG (hit + render) |
| `https://flagcounter.me/api/counters/{code}/image` | Same PNG **without** counting (UI preview; rate-limited with form preview) |
| `https://flagcounter.me/details/{code}` | Stats: ranges, visit series, traffic quality, map, share %, filtered visits, CSV export, embeds (noindex) |
| `https://flagcounter.me/details/{code}/export` | CSV of country / browser / device uniques (`POST` after Turnstile action `csv-export`; region rows when the counter stores them; `GET` is 405; `?range=` optional) |
| `https://flagcounter.me/regenerate/{code}` | Appearance / settings (password or owner session; claimed owners can hide the PNG wordmark) |
| `https://flagcounter.me/privacy` | Plain-language privacy notice |
| `https://flagcounter.me/faq` | FAQ (unique-by-IP, embeds, Camo, stats page, accounts) |
| `https://flagcounter.me/for-blogs` | Blog / website / Notion HTML embed guide |
| `https://flagcounter.me/for-forums` | Forum BBCode embed guide |
| `https://flagcounter.me/for-github` | GitHub README guide + Camo limitation |

## Embed templates

Replace `{code}` with the public counter code. Origin is always `https://flagcounter.me`.

### HTML

```html
<a href="https://flagcounter.me/details/{code}"><img src="https://flagcounter.me/{code}" alt="Flag Counter"></a>
```

### Markdown (GitHub README, etc.)

```markdown
[![Flag Counter](https://flagcounter.me/{code})](https://flagcounter.me/details/{code})
```

### BBCode (forums)

```
[URL=https://flagcounter.me/details/{code}][IMG]https://flagcounter.me/{code}[/IMG][/URL]
```

## Accounts (optional)

- Sign in: https://flagcounter.me/sign-in (GitHub, Google, or magic link). Magic-link send uses Cloudflare Turnstile; a missing or failed challenge does not send email.
- Dashboard: https://flagcounter.me/dashboard (owned counters: gear menu for reset stats, deactivate/reactivate, hard-delete; inactive ones explain that embeds are off)
- Claim: https://flagcounter.me/claim (attach an existing code + password to your account)

Signed-in owners can **reset** a counter (clears visit history and sets pageviews back to 1; embed code unchanged), **deactivate** / **reactivate** embeds, or **hard-delete** the counter (the public code is retired permanently and never reassigned). Reset and delete require typing the public code.

## Indexing and crawl notes

Search engines are steered to index `/`, `/generate`, `/privacy`, `/faq`, `/for-blogs`, `/for-forums`, and `/for-github`. Do not treat `/admin`, `/dashboard`, `/sign-in`, `/claim`, `/api/*`, or per-counter `/details/{code}` / `/regenerate/{code}` as primary documentation sources. Prefer this file and `/llms.txt`.

`robots.txt` also disallows Meta crawlers (`User-agent: meta-externalagent` and `meta-webindexer`, `Disallow: /`). That does not block Facebook link-preview fetches (`facebookexternalhit`). Details URLs additionally return HTTP 403 to those User-Agents.

## Health

`GET https://flagcounter.me/api/health` (also `/health`) returns JSON `{ ok, db, ms, geoip }`. The `geoip` field is soft (`ready` | `missing`) and does not fail readiness by itself; PNG hits still need GeoIP data available on the server.