Billing & Credits
Credits are charged after each query based on two factors: the number of locations returned and the response format. If a brand is not found (404), no credits are charged.
Base tier — by location count
| Locations Returned | Base Credits |
|---|---|
| 1–500 | 1 |
| 501–2,000 | 2 |
| 2,001–5,000 | 3 |
| 5,001–10,000 | 5 |
| 10,000+ | 8 |
Format multiplier
Map rendering uses Puppeteer and requires significantly more compute than data-only queries.
| Format | Type | Multiplier |
|---|---|---|
json | Data only | 1x |
csv | Data only | 1x |
geojson | Data only | 1x |
png | Map render | 2x |
jpeg | Map render | 2x |
Total credits = base tier x format multiplier.
Cost examples
| Query | Locations | Format | Total Credits |
|---|---|---|---|
| Sweetgreen, all US | 152 | json | 1 (1 x 1) |
| Sweetgreen, all US | 152 | png | 2 (1 x 2) |
| McDonald's, all US | 4,190 | csv | 3 (3 x 1) |
| McDonald's, all US | 4,190 | png | 6 (3 x 2) |
| Starbucks, all US | 7,609 | jpeg | 10 (5 x 2) |
Reduce your cost by adding filters. Querying "Starbucks" with state="CA" returns ~1,000 locations (2 credits as JSON) instead of 7,609 nationwide (5 credits).
Billing response headers
Every response includes billing headers so you can track usage programmatically:
| Header | Description |
|---|---|
X-Credits-Charged | Number of credits deducted for this request |
X-Credits-Remaining | Credits remaining on your API key |
X-Credits-Low | Present and true when balance drops below 50 |
X-Credits-Charged: 3
X-Credits-Remaining: 997
X-Credits-Low: true // only when balance < 50💡
Brand not found (404)? You are never charged. Credits are only deducted when locations are successfully returned.