Learn how to use query parameters in the Shovels API to filter and refine your permit and contractor searches.
Query parameters are additional details you include in your API request to specify the data you want to retrieve. They help refine your query to get more relevant results.
curl -X GET \ "https://api.shovels.ai/v2/contractors/search?name=Smith" \ -H "X-API-Key: YOUR_API_KEY_HERE"
The geo_id parameter is a unified geography filter. The same permit search works whether you pass a state abbreviation, zip code, or individual address geo_id—you’re just swapping out the geography level.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Shovels Documentation","colors":{"primary":"#01654D","light":"#E8BD51","dark":"#01654D"},"logo":{"light":"https://mintcdn.com/shovelsai/RpZdSdGGx61eI0yq/assets/shovels-logo.png?fit=max\u0026auto=format\u0026n=RpZdSdGGx61eI0yq\u0026q=85\u0026s=4580f7cd0725b33ba31367d40fda3bbf","dark":"https://mintcdn.com/shovelsai/1PwAyN7q-VPDJL6r/assets/shovels-logo-dark.png?fit=max\u0026auto=format\u0026n=1PwAyN7q-VPDJL6r\u0026q=85\u0026s=48cea9b3276127273eefe9d0d6d9b0b8","href":"https://www.shovels.ai"},"favicon":"https://mintcdn.com/shovelsai/RpZdSdGGx61eI0yq/assets/favicon.png?fit=max\u0026auto=format\u0026n=RpZdSdGGx61eI0yq\u0026q=85\u0026s=fd9ec8e38b5dd0ef58cf2d43fdc71ec3","api":{"playground":{"display":"interactive"},"examples":{"languages":["curl","python","java","go","ruby","php"]},"mdx":{"server":"https://api.shovels.ai/v2"}},"background":{"color":{"light":"#fcfbf8","dark":"#101727"}},"navbar":{"links":[{"href":"mailto:support@shovels.ai","label":"Contact Support"}],"primary":{"type":"button","label":"Free Trial","href":"https://app.shovels.ai/login?mode=register"}},"footer":{"socials":{"discord":"https://discord.gg/Nypja3cKDx","github":"https://github.com/shovelsai","linkedin":"https://linkedin.com/company/shovels"}},"seo":{"metatags":{"og:site_name":"Shovels Documentation","og:type":"website","og:image":"https://docs.shovels.ai/assets/shovels-logo.png","twitter:card":"summary_large_image","twitter:site":"@shovelsai"},"indexing":"navigable"},"fonts":{"heading":{"family":"Poppins"},"body":{"family":"IBM Plex Sans"}},"styling":{"codeblocks":{"theme":{"light":"css-variables","dark":"css-variables"}},"latex":false},"navigation":{"global":{"anchors":[{"anchor":"Data Dictionary","icon":"book-open-cover","href":"https://www.shovels.ai/data-dictionary"},{"anchor":"Coverage Dashboard","icon":"map-pin","href":"https://www.shovels.ai/coverage"},{"anchor":"Community","icon":"discord","href":"https://discord.gg/Nypja3cKDx"},{"anchor":"Blog","icon":"newspaper","href":"https://www.shovels.ai/blog/"}]},"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"shovelsai","hasAudioNarration":false,"actualSubdomain":"shovelsai","customDomains":["docs.shovels.ai"],"gitSource":{"type":"github","owner":"shovelsai","repo":"shovels-docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"chroma":{"liveDeploymentHistoryId":"6ae25e68f001fe32fd8de24d","collectionId":"c26e7288-495c-40a8-9c54-1827a9a99477","schemaVersion":"v3","latestBuiltDeploymentHistoryId":"6ae25e68f001fe32fd8de24d"},"feedback":{"thumbs":true,"edits":true,"issues":true},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6ae25e68f001fe32fd8de24d","clientVersion":"0.0.4044","searchFilterCounts":[{"language":"default","tag":"Knowledge Base","count":202},{"language":"default","tag":"API Reference","count":35},{"language":"default","tag":"Endpoints","count":34},{"language":"default","tag":"API Questions","count":30},{"language":"default","tag":"Data \u0026 Coverage","count":28},{"language":"default","tag":"Documentation","count":18},{"language":"default","tag":"Contractors","count":15},{"language":"default","tag":"Permits","count":12},{"language":"default","tag":"API Basics","count":10},{"language":"default","tag":"Shovels CLI","count":10}]},"assistantConfig":{},"basePath":"","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"byok-sep-25","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-updated-9-15","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":true},"customCss":[{"filePath":"style.css","content":"/* cyrillic-ext */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 400;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v20/-F63fjptAgt5VM-kVkqdyU8n1iIq129k.woff2) format('woff2');\n unicode-range: U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F;\n}\n/* cyrillic */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 400;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v20/-F63fjptAgt5VM-kVkqdyU8n1isq129k.woff2) format('woff2');\n unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;\n}\n/* vietnamese */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 400;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v20/-F63fjptAgt5VM-kVkqdyU8n1iAq129k.woff2) format('woff2');\n unicode-range: U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+0300-0301, U+0303-0304, U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB;\n}\n/* latin-ext */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 400;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v20/-F63fjptAgt5VM-kVkqdyU8n1iEq129k.woff2) format('woff2');\n unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C4, U+2113, U+2C60-2C7F, U+A720-A7FF;\n}\n/* latin */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 400;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v20/-F63fjptAgt5VM-kVkqdyU8n1i8q1w.woff2) format('woff2');\n unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;\n}\n/* cyrillic-ext */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 500;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v20/-F6qfjptAgt5VM-kVkqdyU8n3twJwl1FgtIU.woff2) format('woff2');\n unicode-range: U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F;\n}\n/* cyrillic */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 500;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v20/-F6qfjptAgt5VM-kVkqdyU8n3twJwlRFgtIU.woff2) format('woff2');\n unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;\n}\n/* vietnamese */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 500;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v20/-F6qfjptAgt5VM-kVkqdyU8n3twJwl9FgtIU.woff2) format('woff2');\n unicode-range: U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+0300-0301, U+0303-0304, U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB;\n}\n/* latin-ext */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 500;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v20/-F6qfjptAgt5VM-kVkqdyU8n3twJwl5FgtIU.woff2) format('woff2');\n unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C4, U+2113, U+2C60-2C7F, U+A720-A7FF;\n}\n/* latin */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 500;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v20/-F6qfjptAgt5VM-kVkqdyU8n3twJwlBFgg.woff2) format('woff2');\n unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;\n}\n/* cyrillic-ext */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 600;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v20/-F6qfjptAgt5VM-kVkqdyU8n3vAOwl1FgtIU.woff2) format('woff2');\n unicode-range: U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F;\n}\n/* cyrillic */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 600;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v20/-F6qfjptAgt5VM-kVkqdyU8n3vAOwlRFgtIU.woff2) format('woff2');\n unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;\n}\n/* vietnamese */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 600;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v20/-F6qfjptAgt5VM-kVkqdyU8n3vAOwl9FgtIU.woff2) format('woff2');\n unicode-range: U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+0300-0301, U+0303-0304, U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB;\n}\n/* latin-ext */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 600;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v20/-F6qfjptAgt5VM-kVkqdyU8n3vAOwl5FgtIU.woff2) format('woff2');\n unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C4, U+2113, U+2C60-2C7F, U+A720-A7FF;\n}\n/* latin */\n@font-face {\n font-family: 'IBM Plex Mono';\n font-style: normal;\n font-weight: 600;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/ibmplexmono/v20/-F6qfjptAgt5VM-kVkqdyU8n3vAOwlBFgg.woff2) format('woff2');\n unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;\n}\n:root{--shovels-ink:#101727;--shovels-ink-body:#1e293e;--shovels-ink-secondary:#6b695c;--shovels-label:#837e6c;--shovels-primary:#01654d;--shovels-emerald-dark-rgb:16 185 129;--shovels-emerald-dark:rgb(var(--shovels-emerald-dark-rgb));--shovels-on-emerald:#0e1420;--shovels-surface:#ffffff;--shovels-panel:#f9f7f1;--shovels-subtle:#f0ecdf;--shovels-rule:#e2dcc9;--shovels-rule-strong:#dad3bd;--shovels-dark-panel:#161d2c;--shovels-dark-subtle:#1a2338;--shovels-dark-rule:#2a3550;--shovels-dark-rule-strong:#33415e;--shovels-dark-ink:#d6d0c1;--shovels-dark-ink-secondary:#948d73;--shovels-dark-success-rgb:110 231 183;--shovels-dark-warning-rgb:233 190 81;--shovels-dark-error-rgb:217 135 98;--shovels-success-fill:#e6f2ee;--shovels-success-line:#c6d7ce;--shovels-success-ink:#014d3a;--shovels-warning-fill:#fdfaf0;--shovels-warning-line:#ecd9a4;--shovels-warning-ink:#7a5b18;--shovels-error-fill:#fdf2ee;--shovels-error-line:#a63d27;--shovels-error-ink:#8a3b28;--shovels-structure:Poppins, ui-sans-serif, system-ui, sans-serif;--shovels-identifier:'IBM Plex Mono', ui-monospace, SFMono-Regular, Menlo, monospace;--shovels-lift:0 1px 1px rgba(84, 72, 40, 0.04)}:root:not(.dark){--gray-50:250 249 244;--gray-100:244 241 231;--gray-200:233 228 212;--gray-300:216 209 188;--gray-400:148 142 122;--gray-500:121 116 95;--gray-600:107 105 92;--gray-700:30 41 62;--gray-800:23 32 50;--gray-900:16 23 39;--gray-950:10 15 26;--mint-foreground:var(--shovels-ink);--mint-background:transparent;--mint-token-keyword:var(--shovels-primary);--mint-token-function:var(--shovels-primary);--mint-token-string:#874d33;--mint-token-string-expression:#874d33;--mint-token-constant:#765817;--mint-token-parameter:#55622f;--mint-token-punctuation:#6b6652;--mint-token-comment:#6c6753;--mint-token-link:var(--shovels-primary)}#content-area table th,#sidebar .sidebar-title,.eyebrow{font-family:var(--shovels-structure);font-size:10.5px;font-weight:700;text-transform:uppercase;letter-spacing:.08em;line-height:1.4}:root:not(.dark) .eyebrow{color:var(--shovels-primary)}:root:not(.dark) #content-area table th,:root:not(.dark) #sidebar .sidebar-title{color:var(--shovels-ink-secondary)}:root.dark #content-area table th{color:var(--shovels-dark-ink-secondary)}#content-area .prose:not(.text-sm){font-size:15px;line-height:1.65}#content-area h1,#content-area h2,#content-area h3,#content-area h4{font-weight:600;letter-spacing:-.02em}:root{--font-paper-mono:var(--shovels-identifier)}code,kbd,pre,samp{font-family:var(--shovels-identifier)}:root:not(.dark) #content-area :not(pre)>code{color:var(--shovels-ink);background:var(--shovels-subtle);border:1px solid var(--shovels-rule)}:root.dark #content-area :not(pre)>code{color:var(--shovels-dark-ink);background:var(--shovels-dark-subtle);border:1px solid var(--shovels-dark-rule)}:root.dark{--mint-foreground:var(--shovels-dark-ink);--mint-background:transparent;--mint-token-keyword:var(--shovels-emerald-dark);--mint-token-function:var(--shovels-emerald-dark);--mint-token-string:#d98762;--mint-token-string-expression:#d98762;--mint-token-constant:#ba974a;--mint-token-parameter:#90a653;--mint-token-punctuation:var(--shovels-dark-ink-secondary);--mint-token-comment:#8c8670;--mint-token-link:var(--shovels-emerald-dark)}span[style*=\"--mint-token-function\"],span[style*=\"--mint-token-keyword\"]{font-weight:500;--shiki-dark-font-weight:500}#sidebar .sidebar-group a{font-family:var(--shovels-structure)}:root:not(.dark) #assistant-entry,:root:not(.dark) #search-bar-entry{background:var(--shovels-subtle);border:1px solid var(--shovels-rule)}:root:not(.dark) #assistant-entry *,:root:not(.dark) #search-bar-entry *{color:var(--shovels-ink-secondary)}:root.dark #assistant-entry,:root.dark #search-bar-entry{background:var(--shovels-dark-subtle);border:1px solid var(--shovels-dark-rule)}:root.dark #assistant-entry *,:root.dark #search-bar-entry *{color:var(--shovels-dark-ink-secondary)}#content-area .callout,#content-area .card{border-radius:10px}:root:not(.dark) #content-area .card{background:var(--shovels-surface);border-color:var(--shovels-rule);box-shadow:var(--shovels-lift)}#content-area table td{font-size:13px}#content-area table th{padding-top:8px;padding-bottom:8px;vertical-align:middle}#content-area details table td{overflow-wrap:anywhere}#content-area details table td:first-child{font-family:var(--shovels-identifier);font-weight:500}:root:not(.dark) #content-area table th{background:var(--shovels-subtle);border-bottom:1px solid var(--shovels-rule-strong)}:root:not(.dark) #content-area table td{border-bottom:1px solid var(--shovels-rule)}:root.dark #content-area table th{background:var(--shovels-dark-subtle);border-bottom:1px solid var(--shovels-dark-rule-strong)}:root.dark #content-area table td{border-bottom:1px solid var(--shovels-dark-rule)}:root:not(.dark) #content-area .callout[class*=bg-neutral-]{background:var(--shovels-panel);border-color:var(--shovels-rule)}:root:not(.dark) #content-area .callout[class*=bg-neutral-] svg{color:var(--shovels-label)}:root:not(.dark) #content-area .callout[class*=bg-blue-]{background:var(--shovels-subtle);border-color:var(--shovels-rule-strong)}:root:not(.dark) #content-area .callout[class*=bg-blue-] svg{color:var(--shovels-ink-secondary)}:root:not(.dark) #content-area .callout[class*=bg-green-]{background:var(--shovels-success-fill);border-color:var(--shovels-success-line)}:root:not(.dark) #content-area .callout[class*=bg-green-] svg{color:var(--shovels-primary)}:root:not(.dark) #content-area .callout[class*=bg-yellow-]{background:var(--shovels-warning-fill);border-color:var(--shovels-warning-line)}:root:not(.dark) #content-area .callout[class*=bg-yellow-] svg{color:var(--shovels-warning-ink)}:root:not(.dark) #content-area .callout[class*=bg-red-]{background:var(--shovels-error-fill);border-color:var(--shovels-error-line)}:root:not(.dark) #content-area .callout[class*=bg-red-] svg{color:var(--shovels-error-line)}:root:not(.dark) #content-area .callout[class*=bg-blue-] .prose,:root:not(.dark) #content-area .callout[class*=bg-neutral-] .prose{color:var(--shovels-ink-body)}:root:not(.dark) #content-area .callout[class*=bg-green-] .prose{color:var(--shovels-success-ink)}:root:not(.dark) #content-area .callout[class*=bg-yellow-] .prose{color:var(--shovels-warning-ink)}:root:not(.dark) #content-area .callout[class*=bg-red-] .prose{color:var(--shovels-error-ink)}:root.dark #content-area .callout[class*=bg-neutral-]{background:var(--shovels-dark-panel);border-color:var(--shovels-dark-rule)}:root.dark #content-area .callout[class*=bg-blue-] svg,:root.dark #content-area .callout[class*=bg-neutral-] svg{color:var(--shovels-dark-ink-secondary)}:root.dark #content-area .callout[class*=bg-blue-]{background:var(--shovels-dark-subtle);border-color:var(--shovels-dark-rule-strong)}:root.dark #content-area .callout[class*=bg-green-]{background:rgb(var(--shovels-dark-success-rgb)/.12);border-color:rgb(var(--shovels-dark-success-rgb)/.3)}:root.dark #content-area .callout[class*=bg-green-] svg{color:rgb(var(--shovels-dark-success-rgb))}:root.dark #content-area .callout[class*=bg-yellow-]{background:rgb(var(--shovels-dark-warning-rgb)/.12);border-color:rgb(var(--shovels-dark-warning-rgb)/.3)}:root.dark #content-area .callout[class*=bg-yellow-] svg{color:rgb(var(--shovels-dark-warning-rgb))}:root.dark #content-area .callout[class*=bg-red-]{background:rgb(var(--shovels-dark-error-rgb)/.12);border-color:rgb(var(--shovels-dark-error-rgb)/.3)}:root.dark #content-area .callout[class*=bg-red-] svg{color:rgb(var(--shovels-dark-error-rgb))}:root.dark #content-area .callout[class*=bg-blue-] .prose,:root.dark #content-area .callout[class*=bg-neutral-] .prose{color:var(--shovels-dark-ink)}:root.dark #content-area .callout[class*=bg-green-] .prose{color:rgb(var(--shovels-dark-success-rgb))}:root.dark #content-area .callout[class*=bg-yellow-] .prose{color:rgb(var(--shovels-dark-warning-rgb))}:root.dark #content-area .callout[class*=bg-red-] .prose{color:rgb(var(--shovels-dark-error-rgb))}:root:not(.dark){--accordion-background-color:var(--shovels-panel);--accordion-background-hover:var(--shovels-subtle);--accordion-icon-color:var(--shovels-label)}:root:not(.dark) .method-nav-pill [class*=\"2AB673\"],:root:not(.dark) .tryit-button[class*=\"2AB673\"]{background-color:var(--shovels-primary)}:root:not(.dark) .method-nav-pill [class*=bg-green-],:root:not(.dark) .method-pill[class*=bg-green-]{background-color:var(--shovels-success-fill);color:var(--shovels-primary)}:root.dark .method-nav-pill [class*=\"2AB673\"],:root.dark .tryit-button[class*=\"2AB673\"]{background-color:var(--shovels-emerald-dark);color:var(--shovels-on-emerald)}:root.dark .method-nav-pill [class*=bg-green-],:root.dark .method-pill[class*=bg-green-]{background-color:rgb(var(--shovels-emerald-dark-rgb)/.18);color:var(--shovels-emerald-dark)}:root.dark [class*=bg-primary-dark]{background-color:var(--shovels-emerald-dark)}:root.dark #topbar-cta-button,:root.dark #topbar-cta-button *{color:var(--shovels-on-emerald)}:root:not(.dark) #content-area [class*=bg-red-100]{background-color:var(--shovels-warning-fill);color:var(--shovels-warning-ink);box-shadow:inset 0 0 0 1px var(--shovels-warning-line)}:root.dark #content-area [class*=bg-red-100]{background-color:rgb(var(--shovels-dark-warning-rgb)/.12);color:rgb(var(--shovels-dark-warning-rgb));box-shadow:inset 0 0 0 1px rgb(var(--shovels-dark-warning-rgb)/.3)}"}],"page":{"pagePath":"docs/knowledge-base/api/basics/query-parameters","slug":"/docs/knowledge-base/api/basics/query-parameters","pageMetadata":{"title":"Understanding Query Parameters","description":"Learn how to use query parameters in the Shovels API to filter and refine your permit and contractor searches.","href":"/docs/knowledge-base/api/basics/query-parameters"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Learn how to use query parameters in the Shovels API to filter and refine your permit and contractor searches.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,ol:`ol`,p:`p`,pre:`pre`,span:`span`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,Tip}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Tip)_missingMdxReference(`Tip`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`Query parameters are additional details you include in your API request to specify the data you want to retrieve. They help refine your query to get more relevant results.`}),`\n`,_jsx(Heading,{level:`2`,id:`common-query-parameters`,children:`Common Query Parameters`}),`\n`,_jsx(Heading,{level:`3`,id:`geographic-filtering`,children:`Geographic Filtering`}),`\n`,_jsxs(_components.p,{children:[`The `,_jsx(_components.code,{children:`geo_id`}),` parameter enables precise searching by:`]}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`State (e.g., `,_jsx(_components.code,{children:`CA`}),`, `,_jsx(_components.code,{children:`TX`}),`, `,_jsx(_components.code,{children:`FL`}),`)`]}),`\n`,_jsxs(_components.li,{children:[`Zip code (e.g., `,_jsx(_components.code,{children:`94103`}),`)`]}),`\n`,_jsx(_components.li,{children:`City or county`}),`\n`,_jsx(_components.li,{children:`Specific address`}),`\n`]}),`\n`,_jsx(Heading,{level:`3`,id:`date-filtering`,children:`Date Filtering`}),`\n`,_jsx(_components.p,{children:`Filter permits by date ranges:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`permit_from`}),` - Start date for permit search`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`permit_to`}),` - End date for permit search`]}),`\n`]}),`\n`,_jsx(Heading,{level:`3`,id:`pagination`,children:`Pagination`}),`\n`,_jsx(_components.p,{children:`Control result sets:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`size`}),` - Number of records per page (default: 10, max: 100)`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`cursor`}),` - For cursor-based pagination`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`example-requests`,children:`Example Requests`}),`\n`,_jsx(Heading,{level:`3`,id:`search-permits-in-california-from-2024`,children:`Search permits in California from 2024`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`3`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes css-variables css-variables`,style:{backgroundColor:`var(--mint-background)`,\"--shiki-dark-bg\":`var(--mint-background)`,color:`var(--mint-foreground)`,\"--shiki-dark\":`var(--mint-foreground)`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`3`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`var(--mint-token-function, #0068d6)`,\"--shiki-dark\":`var(--mint-token-function, #0068d6)`},children:`curl`}),_jsx(_components.span,{style:{color:`var(--mint-token-string, #297a3a)`,\"--shiki-dark\":`var(--mint-token-string, #297a3a)`},children:` -X`}),_jsx(_components.span,{style:{color:`var(--mint-token-string, #297a3a)`,\"--shiki-dark\":`var(--mint-token-string, #297a3a)`},children:` GET`}),_jsx(_components.span,{style:{color:`var(--mint-foreground)`,\"--shiki-dark\":`var(--mint-foreground)`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`var(--mint-token-string-expression, #297a3a)`,\"--shiki-dark\":`var(--mint-token-string-expression, #297a3a)`},children:` \"https://api.shovels.ai/v2/permits/search?geo_id=CA\u0026permit_from=2024-01-01\u0026permit_to=2024-12-31\u0026size=100\"`}),_jsx(_components.span,{style:{color:`var(--mint-foreground)`,\"--shiki-dark\":`var(--mint-foreground)`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`var(--mint-token-string, #297a3a)`,\"--shiki-dark\":`var(--mint-token-string, #297a3a)`},children:` -H`}),_jsx(_components.span,{style:{color:`var(--mint-token-string-expression, #297a3a)`,\"--shiki-dark\":`var(--mint-token-string-expression, #297a3a)`},children:` \"X-API-Key: YOUR_API_KEY_HERE\"`})]}),`\n`]})})}),`\n`,_jsx(Heading,{level:`3`,id:`search-contractors-by-name`,children:`Search contractors by name`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`3`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes css-variables css-variables`,style:{backgroundColor:`var(--mint-background)`,\"--shiki-dark-bg\":`var(--mint-background)`,color:`var(--mint-foreground)`,\"--shiki-dark\":`var(--mint-foreground)`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`3`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`var(--mint-token-function, #0068d6)`,\"--shiki-dark\":`var(--mint-token-function, #0068d6)`},children:`curl`}),_jsx(_components.span,{style:{color:`var(--mint-token-string, #297a3a)`,\"--shiki-dark\":`var(--mint-token-string, #297a3a)`},children:` -X`}),_jsx(_components.span,{style:{color:`var(--mint-token-string, #297a3a)`,\"--shiki-dark\":`var(--mint-token-string, #297a3a)`},children:` GET`}),_jsx(_components.span,{style:{color:`var(--mint-foreground)`,\"--shiki-dark\":`var(--mint-foreground)`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`var(--mint-token-string-expression, #297a3a)`,\"--shiki-dark\":`var(--mint-token-string-expression, #297a3a)`},children:` \"https://api.shovels.ai/v2/contractors/search?name=Smith\"`}),_jsx(_components.span,{style:{color:`var(--mint-foreground)`,\"--shiki-dark\":`var(--mint-foreground)`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`var(--mint-token-string, #297a3a)`,\"--shiki-dark\":`var(--mint-token-string, #297a3a)`},children:` -H`}),_jsx(_components.span,{style:{color:`var(--mint-token-string-expression, #297a3a)`,\"--shiki-dark\":`var(--mint-token-string-expression, #297a3a)`},children:` \"X-API-Key: YOUR_API_KEY_HERE\"`})]}),`\n`]})})}),`\n`,_jsx(Tip,{children:_jsxs(_components.p,{children:[`The `,_jsx(_components.code,{children:`geo_id`}),` parameter is a unified geography filter. The same permit search works whether you pass a state abbreviation, zip code, or individual address geo_id—you’re just swapping out the geography level.`]})}),`\n`,_jsx(Heading,{level:`2`,id:`using-filters-efficiently`,children:`Using Filters Efficiently`}),`\n`,_jsx(_components.p,{children:`To optimize your API responses:`}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsx(_components.li,{children:`Apply date filters to narrow results`}),`\n`,_jsx(_components.li,{children:`Use property type filters when relevant`}),`\n`,_jsx(_components.li,{children:`Start with broader geography, then narrow down`}),`\n`,_jsxs(_components.li,{children:[`Use the `,_jsx(_components.code,{children:`/list/*`}),` endpoints to get valid values for filter parameters`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`learn-more`,children:`Learn More`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:_jsx(_components.a,{href:`/api-reference`,children:`API Reference`})}),`\n`,_jsx(_components.li,{children:_jsx(_components.a,{href:`/docs/knowledge-base/api/basics/api-endpoints`,children:`Path vs query parameters`})}),`\n`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"codeStyling":{"theme":{"light":"css-variables","dark":"css-variables"}},"config":{},"pageMetadata":{"title":"Understanding Query Parameters","description":"Learn how to use query parameters in the Shovels API to filter and refine your permit and contractor searches.","href":"/docs/knowledge-base/api/basics/query-parameters"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Common Query Parameters","slug":"common-query-parameters","depth":2,"children":[{"title":"Geographic Filtering","slug":"geographic-filtering","depth":3,"children":[]},{"title":"Date Filtering","slug":"date-filtering","depth":3,"children":[]},{"title":"Pagination","slug":"pagination","depth":3,"children":[]}]},{"title":"Example Requests","slug":"example-requests","depth":2,"children":[{"title":"Search permits in California from 2024","slug":"search-permits-in-california-from-2024","depth":3,"children":[]},{"title":"Search contractors by name","slug":"search-contractors-by-name","depth":3,"children":[]}]},{"title":"Using Filters Efficiently","slug":"using-filters-efficiently","depth":2,"children":[]},{"title":"Learn More","slug":"learn-more","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"shovelsai","siteName":"Shovels Documentation","title":"Understanding Query Parameters - Shovels Documentation","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-08-24T11:12:09.239Z","originalFileLocation":"docs/knowledge-base/api/basics/query-parameters.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Learn how to use query parameters in the Shovels API to filter and refine your permit and contractor searches.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Shovels Documentation\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/shovelsai/0tzx6OgdpifPiQBm/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/shovelsai/0tzx6OgdpifPiQBm/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/shovelsai/0tzx6OgdpifPiQBm/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/shovelsai/0tzx6OgdpifPiQBm/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/shovelsai/0tzx6OgdpifPiQBm/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/shovelsai/0tzx6OgdpifPiQBm/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/shovelsai/0tzx6OgdpifPiQBm/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/shovelsai/0tzx6OgdpifPiQBm/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/shovelsai/0tzx6OgdpifPiQBm/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Understanding Query Parameters - Shovels Documentation\">\u003cmeta data-mint-head property=\"og:description\" content=\"Learn how to use query parameters in the Shovels API to filter and refine your permit and contractor searches.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Shovels Documentation\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.shovels.ai/docs/knowledge-base/api/basics/query-parameters\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://docs.shovels.ai/assets/shovels-logo.png\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Understanding Query Parameters - Shovels Documentation\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Learn how to use query parameters in the Shovels API to filter and refine your permit and contractor searches.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://docs.shovels.ai/assets/shovels-logo.png\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/shovelsai/0tzx6OgdpifPiQBm/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Shovels Documentation\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#01654D\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.shovels.ai/docs/knowledge-base/api/basics/query-parameters\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/docs/knowledge-base/api/basics/query-parameters.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.shovels.ai/#organization\",\"name\":\"Shovels Documentation\",\"url\":\"https://docs.shovels.ai\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/shovelsai/RpZdSdGGx61eI0yq/assets/shovels-logo.png?fit=max\u0026auto=format\u0026n=RpZdSdGGx61eI0yq\u0026q=85\u0026s=4580f7cd0725b33ba31367d40fda3bbf\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.shovels.ai#website\",\"name\":\"Shovels Documentation\",\"url\":\"https://docs.shovels.ai\",\"publisher\":{\"@id\":\"https://docs.shovels.ai/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.shovels.ai/docs/knowledge-base/api/basics/query-parameters#webpage\",\"url\":\"https://docs.shovels.ai/docs/knowledge-base/api/basics/query-parameters\",\"name\":\"Understanding Query Parameters\",\"description\":\"Learn how to use query parameters in the Shovels API to filter and refine your permit and contractor searches.\",\"dateModified\":\"2026-08-24T11:12:09.239Z\",\"isPartOf\":{\"@id\":\"https://docs.shovels.ai#website\"},\"breadcrumb\":{\"@id\":\"https://docs.shovels.ai/docs/knowledge-base/api/basics/query-parameters#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.shovels.ai/docs/knowledge-base/api/basics/query-parameters#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Knowledge Base\",\"item\":\"https://docs.shovels.ai/docs/knowledge-base/index\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"API Questions\",\"item\":\"https://docs.shovels.ai/docs/knowledge-base/api/basics/api-key-access\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"API Basics\",\"item\":\"https://docs.shovels.ai/docs/knowledge-base/api/basics/api-key-access\"},{\"@type\":\"ListItem\",\"position\":4,\"name\":\"Understanding Query Parameters\",\"item\":\"https://docs.shovels.ai/docs/knowledge-base/api/basics/query-parameters\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.shovels.ai/docs/knowledge-base/api/basics/query-parameters#article\",\"headline\":\"Understanding Query Parameters\",\"name\":\"Understanding Query Parameters\",\"description\":\"Learn how to use query parameters in the Shovels API to filter and refine your permit and contractor searches.\",\"url\":\"https://docs.shovels.ai/docs/knowledge-base/api/basics/query-parameters\",\"mainEntityOfPage\":{\"@id\":\"https://docs.shovels.ai/docs/knowledge-base/api/basics/query-parameters#webpage\"},\"image\":\"https://docs.shovels.ai/assets/shovels-logo.png\",\"dateModified\":\"2026-08-24T11:12:09.239Z\",\"publisher\":{\"@id\":\"https://docs.shovels.ai/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.shovels.ai#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Shovels Documentation\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Shovels Documentation","nav":{"global":{"anchors":[{"anchor":"Data Dictionary","icon":"book-open-cover","href":"https://www.shovels.ai/data-dictionary"},{"anchor":"Coverage Dashboard","icon":"map-pin","href":"https://www.shovels.ai/coverage"},{"anchor":"Community","icon":"discord","href":"https://discord.gg/Nypja3cKDx"},{"anchor":"Blog","icon":"newspaper","href":"https://www.shovels.ai/blog/"}]},"tabs":[{"tab":"Documentation","pages":[{"title":"Documentation","href":"/docs/introduction"}]},{"tab":"API Reference","pages":[{"title":"API Reference","href":"/docs/api-reference-about"}]},{"tab":"Release Notes","pages":[{"title":"Release Notes","href":"/release-notes/release-notes"}]},{"tab":"Knowledge Base","groups":[{"group":"Knowledge Base","pages":[{"title":"Shovels Knowledge Base","href":"/docs/knowledge-base"},{"title":"Quick Answers","sidebarTitle":"Quick Answers","href":"/docs/knowledge-base/quick-answers"},{"title":"Shovels Glossary","sidebarTitle":"Glossary","href":"/docs/knowledge-base/glossary"},{"group":"Getting Started","pages":[{"title":"What's Included in the Shovels Free Plan?","href":"/docs/knowledge-base/getting-started/free-trial-guide"},{"title":"How Much Does Shovels Cost?","href":"/docs/knowledge-base/getting-started/pricing-structure"},{"title":"Which Shovels Plan Is Right for Me?","sidebarTitle":"Choosing a Plan","href":"/docs/knowledge-base/getting-started/choosing-a-plan"},{"title":"Should I Use the API or an Enterprise Data License?","sidebarTitle":"API vs EDL","href":"/docs/knowledge-base/getting-started/api-vs-edl"},{"title":"What Makes Shovels Different From Other Permit Data Providers?","href":"/docs/knowledge-base/getting-started/key-differentiators"}]},{"group":"API Questions","pages":[{"group":"API Basics","pages":[{"title":"How to Access Your API Key","href":"/docs/knowledge-base/api/basics/api-key-access"},{"title":"Understanding API Endpoints","description":"Quick overview of Shovels API endpoints. For complete details, see the API Reference documentation.","href":"/docs/knowledge-base/api/basics/api-endpoints"},{"title":"Understanding Query Parameters","href":"/docs/knowledge-base/api/basics/query-parameters"},{"title":"Why is job_value Returned in Cents?","description":"Learn why the Shovels API returns job_value in cents rather than dollars, following industry-standard practices for handling monetary values.","href":"/docs/knowledge-base/api/basics/job-value-cents"},{"title":"What is My API Credit Limit?","href":"/docs/knowledge-base/api/basics/credit-limits"},{"title":"What Are the Shovels API Rate Limits?","href":"/docs/knowledge-base/api/basics/rate-limits"},{"title":"How Do Credits Work?","href":"/docs/knowledge-base/api/basics/request-counts"},{"title":"How Many Permits Can I Retrieve Per API Call?","href":"/docs/knowledge-base/api/basics/permits-per-call"},{"title":"How to Verify Your API Request Was Successful","href":"/docs/knowledge-base/api/basics/successful-requests"},{"title":"Can I Automate API Calls?","href":"/docs/knowledge-base/api/basics/automate-calls"}]},{"group":"Address Resolution","pages":[{"title":"Resolving Addresses to geo_id","href":"/docs/knowledge-base/api/address-resolution/resolving-addresses"},{"title":"What is a geo_id and How Do I Get One?","href":"/docs/knowledge-base/api/address-resolution/geo-id-lookup"},{"title":"State and Zip Code Validation in Address Searches","href":"/docs/knowledge-base/api/address-resolution/state-zip-validation"}]},{"group":"Permits","pages":[{"title":"How to Search for Permits","href":"/docs/knowledge-base/api/permits/permit-search"},{"title":"How to Search Permits by State","href":"/docs/knowledge-base/api/permits/permits-by-state"}]},{"group":"Properties","pages":[{"title":"How to Search for Properties","href":"/docs/knowledge-base/api/properties/property-search"},{"title":"Get Properties by ID","href":"/docs/knowledge-base/api/properties/properties-by-id"},{"title":"Finding Properties With No Permit on Record","href":"/docs/knowledge-base/api/properties/absence-queries"},{"title":"Finding Properties With Unfinaled Permits","href":"/docs/knowledge-base/api/properties/unfinaled-permits"},{"title":"Properties vs Permits: Which Endpoint?","href":"/docs/knowledge-base/api/properties/properties-vs-permits"}]},{"group":"Decisions","pages":[{"title":"How to Search for Decisions","href":"/docs/knowledge-base/api/decisions/searching-decisions"},{"title":"How to Get Decisions by ID","href":"/docs/knowledge-base/api/decisions/decisions-by-id"},{"title":"Where Decisions Are Available","href":"/docs/knowledge-base/api/decisions/decisions-availability"}]},{"group":"Contractors","pages":[{"title":"How to Search for Contractors","href":"/docs/knowledge-base/api/contractors/contractor-search"},{"title":"How to Get Contractor Employee Information","href":"/docs/knowledge-base/api/contractors/employee-data"},{"title":"How to Find a Contractor's Service Area","href":"/docs/knowledge-base/api/contractors/service-area-lookup"},{"title":"How to Filter Contractors by Company Size","href":"/docs/knowledge-base/api/contractors/filtering-by-size"},{"title":"How to Identify Independent Contractors","href":"/docs/knowledge-base/api/contractors/independent-contractors"}]},{"group":"Error Handling","pages":[{"title":"API Error Handling","href":"/docs/knowledge-base/api/errors/error-handling"},{"title":"What Does a 422 Error Mean in the Shovels API?","href":"/docs/knowledge-base/api/errors/422-error"}]}]},{"group":"Shovels CLI","pages":[{"title":"How Do I Install the Shovels CLI?","sidebarTitle":"Installation","href":"/docs/knowledge-base/cli/installation"},{"title":"How Does CLI Authentication Work?","sidebarTitle":"Authentication","href":"/docs/knowledge-base/cli/authentication"},{"title":"What Commands Are Available in the CLI?","sidebarTitle":"Commands Overview","href":"/docs/knowledge-base/cli/commands-overview"},{"title":"How Do I Query Properties from the CLI?","sidebarTitle":"Properties","href":"/docs/knowledge-base/cli/properties"},{"title":"How Do I Run Absence Searches in the CLI?","sidebarTitle":"Absence \u0026 Trust","href":"/docs/knowledge-base/cli/absence-and-trust"},{"title":"How Does CLI Output and Pagination Work?","sidebarTitle":"Output \u0026 Pagination","href":"/docs/knowledge-base/cli/output-and-pagination"},{"title":"What Do CLI Exit Codes and Errors Mean?","sidebarTitle":"Error Codes","href":"/docs/knowledge-base/cli/error-codes"},{"title":"How Do I Use the CLI in Scripts and AI Agents?","sidebarTitle":"Scripting \u0026 AI Agents","href":"/docs/knowledge-base/cli/scripting-and-agents"}]},{"group":"Google Sheets Add-on","pages":[{"title":"How Do I Install the Shovels Add-on for Google Sheets?","sidebarTitle":"Installation","href":"/docs/knowledge-base/sheets/installation"},{"title":"How Does the API Key Work in Google Sheets?","sidebarTitle":"API Key","href":"/docs/knowledge-base/sheets/api-key"},{"title":"What Formulas Does the Shovels Add-on Provide?","sidebarTitle":"Formulas","href":"/docs/knowledge-base/sheets/formulas"},{"title":"How Do I Look Up Contractors by Name in Google Sheets?","sidebarTitle":"Contractor Lookups","href":"/docs/knowledge-base/sheets/contractor-lookups"},{"title":"How Do I Get Permits for an Address, ZIP Code, County, or State in Google Sheets?","sidebarTitle":"Permits by Location","href":"/docs/knowledge-base/sheets/permits-by-location"},{"title":"How Do Credits, Caching, and Refreshing Work in Google Sheets?","sidebarTitle":"Credits \u0026 Refreshing","href":"/docs/knowledge-base/sheets/credits-and-refreshing"},{"title":"Why Does a Cell Show \"Shovels: fetching…\" or an Error?","sidebarTitle":"Troubleshooting","href":"/docs/knowledge-base/sheets/troubleshooting"}]},{"group":"Shovels Online","pages":[{"title":"How Shovels Online Works","href":"/docs/knowledge-base/shovels-online/how-it-works"},{"title":"What Is Charlie?","sidebarTitle":"Charlie","href":"/docs/knowledge-base/shovels-online/charlie"},{"title":"Search Functionality in Shovels Online","href":"/docs/knowledge-base/shovels-online/search-functionality"},{"title":"Using Filters in Shovels Online","href":"/docs/knowledge-base/shovels-online/filters-and-sorting"},{"title":"Permit Data Downloads","href":"/docs/knowledge-base/shovels-online/permit-downloads"},{"title":"Contractor Data Downloads","href":"/docs/knowledge-base/shovels-online/contractor-downloads"},{"title":"How Do I Cancel My Shovels Subscription?","href":"/docs/knowledge-base/shovels-online/cancel-subscription"}]},{"group":"Data \u0026 Coverage","pages":[{"group":"Permits","pages":[{"title":"Tracking Multiple Permits at a Property","href":"/docs/knowledge-base/data/permits/permit-tracking"},{"title":"How Permits Are Tracked Through Their Lifecycle","href":"/docs/knowledge-base/data/permits/permit-lifecycle"},{"title":"What Do Permit Statuses Mean in Shovels?","href":"/docs/knowledge-base/data/permits/permit-statuses"},{"title":"Why Some Permits Don't Have Addresses","href":"/docs/knowledge-base/data/permits/permits-without-addresses"},{"title":"Understanding Permit Unique Identifiers","href":"/docs/knowledge-base/data/permits/unique-identifiers"},{"title":"Understanding Start and End Dates","href":"/docs/knowledge-base/data/permits/start-end-dates"},{"title":"How to Check Project Completion and Inspection Status","href":"/docs/knowledge-base/data/permits/project-completion"},{"title":"Residential vs Commercial Permit Distribution","href":"/docs/knowledge-base/data/permits/permit-distribution"}]},{"group":"Decisions","pages":[{"title":"What are Shovels Decisions?","href":"/docs/knowledge-base/data/decisions/overview"},{"title":"Decision Categories","href":"/docs/knowledge-base/data/decisions/decision-categories"},{"title":"Decision Data Fields","href":"/docs/knowledge-base/data/decisions/data-fields"},{"title":"From Decision to Permit: The Development Lifecycle","href":"/docs/knowledge-base/data/decisions/decision-to-permit"}]},{"group":"Contractors","pages":[{"title":"Contractor Data Overview","href":"/docs/knowledge-base/data/contractors/contractor-data-overview"},{"title":"Assessing Contractor Quality Through Data","href":"/docs/knowledge-base/data/contractors/quality-indicators"},{"title":"Contractor Contact Information","href":"/docs/knowledge-base/data/contractors/contact-information"},{"title":"Industry Classification Data (NAICS \u0026 SIC)","href":"/docs/knowledge-base/data/contractors/industry-classification"},{"title":"Why Contractor IDs Can Change","href":"/docs/knowledge-base/data/contractors/id-changes"}]},{"group":"Residents","pages":[{"title":"Understanding Shovels Resident Data","href":"/docs/knowledge-base/data/residents/resident-data"},{"title":"Understanding the Homeowner Field","href":"/docs/knowledge-base/data/residents/homeowner-field"}]},{"group":"Geographic","pages":[{"title":"Latitude and Longitude Data","href":"/docs/knowledge-base/data/geographic/coordinates-geocoding"},{"title":"What is a Jurisdiction (AHJ)?","href":"/docs/knowledge-base/data/geographic/jurisdictions"},{"title":"What Areas Does Shovels Cover?","href":"/docs/knowledge-base/data/geographic/coverage-areas"}]},{"group":"Data Quality","pages":[{"title":"Where Does Shovels Get Its Data?","href":"/docs/knowledge-base/data/quality/data-sources"},{"title":"How Shovels Verifies Data Accuracy","href":"/docs/knowledge-base/data/quality/verification-methods"},{"title":"How Often Does Shovels Update Its Data?","href":"/docs/knowledge-base/data/quality/refresh-frequency"},{"title":"Data Labeling and Annotation Process","href":"/docs/knowledge-base/data/quality/labeling-process"},{"title":"Historical Data Coverage","href":"/docs/knowledge-base/data/quality/historical-data"},{"title":"Why Am I Getting So Few Results?","href":"/docs/knowledge-base/data/quality/few-results"}]}]},{"group":"Enterprise (EDL)","pages":[{"title":"What is Shovels EDL (Enterprise Data License)?","href":"/docs/knowledge-base/edl/overview"},{"title":"How EDL Deliveries Work","href":"/docs/knowledge-base/edl/monthly-deliveries"},{"title":"Tracking New vs Modified Records in EDL","href":"/docs/knowledge-base/edl/record-tracking"},{"title":"Contractor Deduplication in EDL","href":"/docs/knowledge-base/edl/contractor-deduplication"},{"title":"Understanding the is_representative Field","href":"/docs/knowledge-base/edl/is-representative-field"},{"title":"Getting Resident Contact Information in EDL","href":"/docs/knowledge-base/edl/resident-contact-info"},{"title":"Requesting Manual Reports","href":"/docs/knowledge-base/edl/manual-reports"},{"title":"EDL Data Formats and File Sizes","href":"/docs/knowledge-base/edl/data-formats"},{"title":"Requesting Sample Records","href":"/docs/knowledge-base/edl/sample-records"}]},{"group":"Company","pages":[{"title":"Shovels Contact Information","href":"/docs/knowledge-base/company/contact-information"},{"title":"How Property Types Are Categorized","href":"/docs/knowledge-base/company/property-types"},{"title":"What Is Shovels' Refund Policy?","href":"/docs/knowledge-base/company/refund-policy"},{"title":"What Can and Can't I Do With Shovels Data?","href":"/docs/knowledge-base/company/data-usage-terms"}]}]}]}]},"basePath":"","title":"Understanding Query Parameters - Shovels Documentation","buildId":"dpl_DeHjVRGfFnhYQwHnfC2pjeXXv8h9","deploymentId":"dpl_DeHjVRGfFnhYQwHnfC2pjeXXv8h9","dynamics":[],"chunks":[]}
