Search local businesses

This page documents the canonical HTTP contract. Switch to the CLI example when you want the operator workflow.

Billing is per Maps query (2 credits per query under the current search definition). Explicit areas can fan out to multiple queries, so read credits_used and pricing_rule from each response rather than estimating from result count.

Body parameters

queryrequired
string
Required nonblank query, 2–500 characters; whitespace normalized.
limit · optional
integer
Maximum businesses to return. Default: 25. Range: 1–100.
country · optional
string
ISO 3166-1 alpha-2 code. Default: us.
language · optional
string
Search language code. Default: en.
page · optional
integer
Page number. Default: 1; must be at least 1.
areas · optional
array<LocalBusinessArea>
Up to 10 explicit geographic cells; when nonempty, length must not exceed max_queries. US postal_code values must be ZIP/ZIP+4; UK postal_district values must match the UK district format.
max_queries · optional
integer
Maximum area queries. Default: 10. Range: 1–10.

Name	Type	Description
queryrequired	string	Required nonblank query, 2–500 characters; whitespace normalized.
limit	integer	Maximum businesses to return. Default: 25. Range: 1–100.
country	string	ISO 3166-1 alpha-2 code. Default: us.
language	string	Search language code. Default: en.
page	integer	Page number. Default: 1; must be at least 1.
areas	array<LocalBusinessArea>	Up to 10 explicit geographic cells; when nonempty, length must not exceed max_queries. US postal_code values must be ZIP/ZIP+4; UK postal_district values must match the UK district format.
max_queries	integer	Maximum area queries. Default: 10. Range: 1–10.

Definitions

LocalBusinessArea

One explicit geographic cell. Extra object fields are rejected.

Fields

type · optional
string
Allowed: postal_code, postal_district, locality, or custom. Default: postal_code.
valuerequired
string
Required, 1–80 characters.
label · optional
string|null
Optional label, maximum 120 characters.

Name	Type	Description
type	string	Allowed: postal_code, postal_district, locality, or custom. Default: postal_code.
valuerequired	string	Required, 1–80 characters.
label	string\|null	Optional label, maximum 120 characters.

Errors

Status	Meaning
400	The search/provider rejected the request.
401	Invalid API key or missing auth.
403	Missing search:run scope.
422	The JSON request does not satisfy the typed request model.

Example

bash

curl -X POST "https://app.autotouch.ai/api/search/local-businesses" \
  -H "Authorization: Bearer stk_your_key_id.your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "orthodontists in Austin Texas",
    "limit": 25,
    "country": "us",
    "language": "en",
    "areas": [{"type": "postal_code", "value": "78701", "label": "Austin"}],
    "max_queries": 1
  }'

Request body

json

{
  "query": "orthodontists in Austin Texas",
  "limit": 25,
  "country": "us",
  "language": "en",
  "areas": [{"type": "postal_code", "value": "78701", "label": "Austin"}],
  "max_queries": 1
}

Response example

json

{
  "query": "orthodontists in Austin Texas",
  "items": [
    {
      "title": "Austin Orthodontics",
      "address": "123 Main St, Austin, TX",
      "website": "https://austinortho.example",
      "rating": 4.8
    }
  ],
  "total_found": 1,
  "billable_results": 1,
  "credits_used": 2,
  "pricing_rule": "2 credits per Maps query (Serper usage)",
  "metadata": {}
}