TownRanker GeoGrid API Documentation

Authentication

All API requests require authentication using your API key. Include it in the request headers:

X-API-Key: gt_your_api_key_here

Or use the Authorization header:

Authorization: Bearer gt_your_api_key_here

Keep your API key secret

Never expose your API key in client-side code. Use it only in server-side applications.

Rate Limits

60

requests/minute (standard)

10

requests/minute (check endpoints)

Rate limit headers are included in every response:

                        
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1699234567

Error Handling

Status	Meaning
`200`	Success
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`402`	Payment Required - Insufficient tokens
`403`	Forbidden - Feature not available on your plan
`404`	Not Found - Resource doesn't exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Server Error

Account

GET /api/v1/account

Get your account info, token balance, and limits.

Example Request

curl -H "X-API-Key: gt_your_key" https://townranker.com/api/v1/account

Response

{
  "success": true,
  "account": {
    "email": "you@example.com",
    "name": "Your Name"
  },
  "tokens": {
    "balance": 5000,
    "bonusTokens": 200,
    "total": 5200,
    "pricePerToken": 0.006
  },
  "limits": {
    "maxCampaigns": -1,
    "maxKeywordsPerCampaign": -1,
    "maxGridSize": "15x15"
  }
}

GET /api/v1/account/usage

Get token usage statistics.

Query Parameters

days Number of days to look back (default: 30)

Quick Check

POST /api/v1/check

Run a quick rank check for a single keyword without creating a campaign. Perfect for one-off checks or testing.

Request Body

{
  "keyword": "window replacement near me",
  "location": { "lat": 33.4484, "lng": -112.0740 },
  "targetDomain": "example.com",
  "gridSize": { "rows": 5, "cols": 5 },
  "radiusMiles": 10,
  "includeMapPack": false
}

Parameters

`keyword` *	Search term to check rankings for
`location` *	Center point with lat/lng coordinates
`targetDomain` *	Domain to find in search results
`gridSize`	Grid dimensions (default: 5x5)
`radiusMiles`	Radius of grid coverage (default: 10)
`includeMapPack`	Also check Google Maps pack (default: false)

Example Request

curl -X POST https://townranker.com/api/v1/check \
  -H "X-API-Key: gt_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "window replacement near me",
    "location": { "lat": 33.4484, "lng": -112.0740 },
    "targetDomain": "windowsdoorsnearme.com",
    "gridSize": { "rows": 5, "cols": 5 }
  }'

Response

{
  "success": true,
  "keyword": "window replacement near me",
  "summary": {
    "averageRank": 4.2,
    "rankedPoints": 18,
    "totalPoints": 25,
    "top3Count": 8,
    "top10Count": 16
  },
  "grid": [
    { "row": 0, "col": 0, "lat": 33.51, "lng": -112.14, "rank": 3 },
    { "row": 0, "col": 1, "lat": 33.51, "lng": -112.10, "rank": 5 },
    ...
  ],
  "tokensUsed": 25,
  "remainingBalance": 4975
}

Campaigns

GET /api/v1/campaigns

List all your campaigns.

POST /api/v1/campaigns

Create a new campaign for ongoing rank tracking.

{
  "name": "Phoenix SEO Campaign",
  "businessName": "My Window Company",
  "domain": "example.com",
  "centerLocation": { "lat": 33.4484, "lng": -112.0740 },
  "gridConfig": { "rows": 5, "cols": 5, "radiusMiles": 10 }
}

POST /api/v1/campaigns/:id/check

Run a rank check for all keywords in a campaign.

Parameters

`dryRun`	Preview cost without running (default: false)
`includeMapPack`	Include map pack checks (default: false)

Keywords

POST /api/v1/campaigns/:id/keywords

Add keywords to a campaign.

{
  "keywords": [
    "window replacement near me",
    "best windows phoenix",
    "vinyl windows installation"
  ]
}

GET /api/v1/campaigns/:id/keywords

List all keywords in a campaign.

Results

GET /api/v1/campaigns/:id/results

Get rank check results.

Query Parameters

`keywordId`	Filter by specific keyword
`startDate`	Filter results after date (ISO 8601)
`limit`	Max results to return (default: 100)

GET /api/v1/campaigns/:id/grid

Get grid data for visualization (heatmap format).

Tokens

POST /api/v1/tokens/purchase

Purchase tokens (preview mode - contact support for purchases).

{
  "amountUSD": 50
}

POST /api/v1/tokens/auto-reload

Configure auto-reload settings.

{
  "enabled": true,
  "threshold": 100,
  "amount": 50
}

GET /api/v1/tokens/transactions

Get token transaction history.

Token Pricing

$0.006

per token

1 token

= 1 grid point check

25 tokens

= 5x5 grid check

Example Costs

Check Type	Tokens	Cost
5x5 grid (1 keyword)	25	$0.15
7x7 grid (1 keyword)	49	$0.29
5x5 grid + Map Pack (1 keyword)	50	$0.30
Campaign: 5 keywords, 5x5 grid	125	$0.75