=== AgentTally State Agent Statistics ===
Contributors: usrealtorlist
Tags: real estate, statistics, agents, data, block
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.3
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Show how many real estate agents work in each US state. Sortable table or a single-state figure, as a block or shortcode. No external calls.

== Description ==

**AgentTally State Agent Statistics** publishes a dataset compiled from public brokerage listings: how many licensed real estate agents are working in each US state, how many are reachable by phone, and how many hold a producer award from their brokerage.

Drop the block on a page and you get a clean table that inherits your theme's fonts and colours. Every option (one state or the full table, how many states, sort order, columns) is in the block's sidebar, so there is nothing to memorise. Want a single figure inside a sentence? Pick a state and it renders something like "28,937 real estate agents in Florida (as of August 2026)" inline.

= How to use =

1. Edit a page or post, click the + (Block Inserter) and search for **AgentTally**.
2. Add the **AgentTally State Agent Statistics** block. The full table appears straight away.
3. Use the block settings in the sidebar to show one state, limit to the top N, change the sort or the columns.

Using the Classic Editor, a widget or a page builder? Use the shortcode: `[agenttally_state_agent_stats]` for the table, `[agenttally_state_agent_stats state="TX"]` for one state. **Tools → AgentTally** (also linked as "How to use" on the Plugins screen) lists every option with examples.

This is a **statistics** plugin, not an agent directory. It does not manage your team, import your roster, or create profile pages. It publishes numbers you can cite.

= Why it exists =

Market report pages, brokerage blogs and real estate news posts constantly need a number like "how many agents are there in Texas". Those figures are usually either missing, years out of date, or copied from a press release nobody can check. This ships a current, per-state dataset so you can put a real number on the page.

= Features =

* **Sortable table** — by agent count, state name, phone coverage or award holders
* **Single-state inline figure** — `[agenttally_state_agent_stats state="TX"]` for use mid-sentence
* **Block with sidebar settings** — pick the state, top N, sort and columns without touching a shortcode; the preview is live
* **Shortcode too** — for the Classic Editor and page builders; both produce identical markup
* **Choose your columns** — `[agenttally_state_agent_stats columns="agents"]` for just the counts
* **Top N** — `[agenttally_state_agent_stats limit="10"]` for the ten largest states
* **Theme native** — inherits your fonts and colours instead of imposing its own
* **Fast** — one small stylesheet, loaded only on pages that use the shortcode. No jQuery.
* **No external requests** — the dataset ships inside the plugin. Nothing phones home, so nothing to disclose and nothing to break.
* **Dated** — the table says "Data as of <month year>" so readers know how current the figures are
* **No attribution by default** — an optional source line can be switched on in the block settings or with `credit="yes"`

= Data =

Figures are compiled from the public agent rosters that national brokerages publish themselves, covering nine major brands. Every agent counted has a published, working email address, which is why the totals are lower than licence-registry figures that include inactive licensees.

= How current is the data? =

The figures are a dated snapshot, not a live feed. Each release bundles the latest compiled dataset, and the table (and the inline figure) shows the month it was compiled, for example "Data as of August 2026". A new dataset ships with a plugin update each quarter; update the plugin to get it.

The data is bundled on purpose. A live lookup would mean your site calling our server on page views, which would send your visitors' requests to a third party (a privacy disclosure you would need to make), slow your pages, and break whenever that server did. Bundled, the plugin makes no outside requests at all.

== Installation ==

1. Upload the plugin to `/wp-content/plugins/`, or install through **Plugins → Add New**.
2. Activate it.
3. Add the **AgentTally State Agent Statistics** block to any page (search the Block Inserter for "AgentTally"), or use `[agenttally_state_agent_stats]`. See **Tools → AgentTally** for every option.

== Frequently Asked Questions ==

= Does this send data anywhere? =

No. The plugin makes no external requests at all. The statistics are a JSON file bundled with the plugin, read from disk when a page using the shortcode is rendered.

= Is this an agent directory? =

No. It does not store or display your own agents. It shows state level counts. If you want a "Meet Our Agents" page, you want a directory plugin instead.

= Where do the numbers come from? =

From the agent rosters national brokerages publish on their own websites. Only agents with a published, working email are counted, so the figures are deliberately conservative compared with state licence registries that include inactive licensees.

= How often is it updated? =

A new dataset ships with a plugin update each quarter. The table shows "Data as of <month year>" so readers can see how current it is.

= Do I need to know the shortcode? =

No. The block's sidebar has every option. The shortcode is there for the Classic Editor, widgets and page builders, and **Tools → AgentTally** lists it with examples.

= Can I show only some states? =

Use `limit` for the largest N, or `state` for a single one. Example: `[agenttally_state_agent_stats limit="10"]`.

== Screenshots ==

1. The statistics table on a page, inheriting the theme's styling.
2. A single state figure used inline in a sentence.
3. The block in the editor.

== Changelog ==

= 1.0.3 =
* The block now has sidebar settings (state, number of states, sort, columns, source line) and a live preview, so no shortcode knowledge is needed.
* New help page under Tools → AgentTally, linked as "How to use" on the Plugins screen, with block steps and shortcode examples.
* The table and the inline figure now show "Data as of <month year>" from the bundled dataset.
* The source credit line is now off by default (opt in with the block toggle or credit="yes").

= 1.0.2 =
* Packaging fix: the release archive now carries directory entries, so it installs and activates cleanly in every unzipper (including WordPress Playground). No functional change.

= 1.0.1 =
* Renamed to AgentTally State Agent Statistics; new shortcode name [agenttally_state_agent_stats]; readme wording tightened.

= 1.0.0 =
* First release. Sortable state table, single-state inline figure, block and shortcode.
