> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tyrionurl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Geo Heatmaps

> Visualize where in the world your audience is clicking — down to the city level.

## What are Geo Heatmaps?

The Geographic Heatmap in TyrionURL overlays click density onto a world map, letting you see at a glance where your audience is concentrated. Darker or more intense regions indicate higher click volume. You can zoom into individual countries and view city-level breakdowns for precise geographic intelligence.

***

## Accessing the Geo Heatmap

<Steps>
  <Step title="Open Link Analytics">
    From your dashboard, click the **Analytics** icon on any link to open its analytics view.
  </Step>

  <Step title="Scroll to the Geographic Section">
    The geo heatmap and geographic breakdown are located in the **Geography** panel of the analytics dashboard.

    <Frame>
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/docs-tyrionurl/images/geo-heatmap.png" alt="Geographic heatmap showing global click distribution" />
    </Frame>
  </Step>

  <Step title="Explore the Map">
    * **Hover** over any region to see its click count
    * **Click** a country to zoom in and see city-level data for that country
    * Use the **Country / City toggle** to switch between views
  </Step>
</Steps>

***

## Heatmap Views

### Country-Level View

The default view shows click density across all countries. A data table alongside the map ranks countries by click volume:

| Column         | Description                           |
| -------------- | ------------------------------------- |
| **Country**    | Country name with flag icon           |
| **Clicks**     | Total click count from this country   |
| **% of Total** | Share of all clicks from this country |

### City-Level View

Switch to the city-level breakdown to see a more granular picture:

* City name and country
* Click count and percentage
* Available for any country where city data has been captured

<Info>
  City-level data depends on the accuracy of IP geolocation. Rural or VPN traffic may be attributed to the nearest major city.
</Info>

***

## API Endpoints for Geographic Data

Geographic data is available via API for developer integrations:

```
GET /api/analytics/geo/:shortCode/countries     → country-level breakdown
GET /api/analytics/geo/:shortCode/cities        → city-level breakdown
```

***

## Use Cases

<AccordionGroup>
  <Accordion title="Validate geo-targeting of ads" icon="bullseye">
    If your paid ads are targeted at a specific region, the heatmap should show a concentration there. A mismatch suggests your targeting or attribution setup needs review.
  </Accordion>

  <Accordion title="Identify organic international audiences" icon="globe">
    If a significant portion of your traffic is coming from an unexpected country, it may signal an organic opportunity worth pursuing (localized content, regional pricing, etc.).
  </Accordion>

  <Accordion title="Plan content localization" icon="language">
    High traffic from a non-English-speaking country is a signal to invest in localization for that market.
  </Accordion>

  <Accordion title="Measure event or campaign reach" icon="flag">
    For regional campaigns (e.g., a local event, a country-specific promotion), the heatmap quickly shows whether your reach stayed within the intended region.
  </Accordion>
</AccordionGroup>

***

## Best Practices

<Check>Compare geo data across multiple links in the same campaign to identify which channels drive the most geographically relevant traffic.</Check>
<Check>Filter by date range when evaluating geo impact for a specific campaign window.</Check>
<Check>Use city-level data for hyper-local campaigns (e.g., pop-up events, city-specific offers).</Check>

***

## Common Mistakes

<Warning>
  **Treating all VPN traffic as real location data** — Users on VPNs may appear in unexpected countries. If you see anomalous spikes in specific countries, consider VPN usage as a potential cause.
</Warning>

***

## Related Pages

<CardGroup cols={2}>
  <Card title="Analytics Dashboard" icon="chart-line" href="/analytics/overview">
    Full analytics overview including device and referrer data.
  </Card>

  <Card title="Live Traffic" icon="signal" href="/analytics/live-traffic">
    Watch clicks arrive in real time.
  </Card>
</CardGroup>