Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.shovels.ai/llms.txt

Use this file to discover all available pages before exploring further.

All CLI output is valid JSON written to stdout. Errors go to stderr. This makes the CLI safe to pipe into jq, scripts, or other tools without worrying about mixed output.

​
Response Format

​
Paginated Responses (search commands)

{
  "data": [
    { "id": "...", "description": "...", "status": "final" }
  ],
  "meta": {
    "count": 50,
    "has_more": true,
    "credits_used": 1,
    "credits_remaining": 9999
  }
}

​
Single Object Responses (get commands with one ID)

{
  "data": {
    "id": "...",
    "name": "...",
    "permit_count": 42
  },
  "meta": {
    "credits_used": 1,
    "credits_remaining": 9999
  }
}

​
Batch Responses (get commands with multiple IDs)

{
  "data": [
    { "id": "ABC", "name": "..." },
    { "id": "DEF", "name": "..." }
  ],
  "meta": {
    "count": 2,
    "missing": ["UNKNOWN_ID"],
    "credits_used": 1,
    "credits_remaining": 9999
  }
}
The missing array lists any IDs that weren’t found.

​
Pagination with —limit

The --limit flag controls how many records to return. The CLI handles cursor-based pagination internally — you never need to manage cursors yourself.
ValueBehavior
--limit 50 (default)Return up to 50 records
--limit 500Return up to 500 records
--limit allFetch all records (capped by --max-records)
# Get first 10 results
shovels permits search --geo-id 92024 \
  --permit-from 2024-01-01 --permit-to 2024-12-31 \
  --limit 10

# Get all results (up to 10,000 by default)
shovels permits search --geo-id 92024 \
  --permit-from 2024-01-01 --permit-to 2024-12-31 \
  --limit all

​
—max-records

When using --limit all, the --max-records flag sets the upper bound (default: 10,000, maximum: 100,000): 
shovels permits search --geo-id CA \
  --permit-from 2024-01-01 --permit-to 2024-12-31 \
  --tags solar --limit all --max-records 50000

​
—include-count

Add --include-count to include the total number of matching records in the response: 
shovels permits search --geo-id 92024 \
  --permit-from 2024-01-01 --permit-to 2024-12-31 \
  --tags solar --include-count --limit 1

{
  "data": ["..."],
  "meta": {
    "count": 1,
    "has_more": true,
    "total_count": {
      "value": 581,
      "relation": "eq"
    },
    "credits_used": 1,
    "credits_remaining": 9999
  }
}
Total counts are exact up to 10,000 ("relation": "eq"). Above 10,000, the count is approximate ("relation": "gte" means “at least this many”).

​
Credit Tracking

Every response includes credits_used and credits_remaining in the meta object. This lets you monitor usage without making a separate API call. To check your overall credit status: 
shovels usage

​
Data Types in Responses

Field TypeFormatExample
DatesISO 8601 (YYYY-MM-DD)"2024-06-15"
Money amountsInteger cents150000 = $1,500.00
RatingsFloat 0-54.2
Pass ratesInteger 0-10085 (percentage)
Coordinates[lat, lng] float array[32.87, -117.25]
geo_idsBase64-encoded string"Q2l0eXxGTHxNaWFtaQ"