Quickstart

What you’ll build

A basic flow that takes user text like Seattle and returns:

a stable geo_id
current permits for that geo
permit-scoped leads and stats for that geo
active geo-scoped signals for that geo

For a complete signal list and timing guide, see Signals Catalog.

Prerequisites

API key
curl

0. Set environment variables

export BASE_URL="https://api.homelogs.io"
export API_KEY="YOUR_API_KEY"

1. Resolve user input to `geo_id`

curl -sS -G "$BASE_URL/v1/locations/resolve" \
  -H "X-API-Key: $API_KEY" \
  --data-urlencode "query=Seattle" \
  --data-urlencode "state=WA" \
  --data-urlencode "limit=5"

Pick one candidates[].geo_id. For permit-scoped signals, pick a non-property geo_id such as a city, county, zip, jurisdiction, or state.

2. Fetch permits for that geo

export GEO_ID="<paste candidates[0].geo_id>"

curl -sS -G "$BASE_URL/v1/permits/search" \
  -H "X-API-Key: $API_KEY" \
  --data-urlencode "geo_id=$GEO_ID" \
  --data-urlencode "limit=25" \
  --data-urlencode "sort=desc"

If next_cursor is not null, request the next page:

curl -sS -G "$BASE_URL/v1/permits/search" \
  -H "X-API-Key: $API_KEY" \
  --data-urlencode "geo_id=$GEO_ID" \
  --data-urlencode "limit=25" \
  --data-urlencode "cursor=CURSOR_TOKEN"

3. Fetch permit-scoped leads for that geo

Use the same geo_id for permit signal reads.

curl -sS -G "$BASE_URL/v1/signals/permit/leads" \
  -H "X-API-Key: $API_KEY" \
  --data-urlencode "geo_id=$GEO_ID" \
  --data-urlencode "signal_keys=site_prep_issued_nowcast,new_construction_issued_nowcast" \
  --data-urlencode "limit=25"

By default, permit leads return only rows inside the freshness window. Add include_stale=true to include older rows.

4. Fetch permit-scoped stats for that geo

curl -sS -G "$BASE_URL/v1/signals/permit/stats" \
  -H "X-API-Key: $API_KEY" \
  --data-urlencode "geo_id=$GEO_ID" \
  --data-urlencode "signal_keys=framing_nowcast_early,rough_in_nowcast_early"

If you want the more conservative timing variants, swap in:

framing_window_late
rough_in_window_late

5. Fetch active geo-scoped signals for that geo

curl -sS -G "$BASE_URL/v1/signals/geo/location/$GEO_ID" \
  -H "X-API-Key: $API_KEY" \
  --data-urlencode "signal_keys=roofing_activity_hotspot,hvac_activity_hotspot"

6. Search geo-scoped signals across a state

curl -sS -G "$BASE_URL/v1/signals/geo/search" \
  -H "X-API-Key: $API_KEY" \
  --data-urlencode "state=WA" \
  --data-urlencode "geo_type=city" \
  --data-urlencode "signal_keys=roofing_activity_hotspot" \
  --data-urlencode "decision=positive" \
  --data-urlencode "min_score=0.5" \
  --data-urlencode "limit=25"

Common first-run issues

403: missing/invalid API key
422: invalid query format, unsupported permit-scoped geo type, or bad cursor
404: valid request but no matching resource

See Troubleshooting. Want more detail on signal fields and scoring behavior? See Signals Catalog and Signals & Methodology.

Getting Started

Identity & Signals

What you’ll build

Prerequisites

0. Set environment variables

1. Resolve user input to `geo_id`

2. Fetch permits for that geo

3. Fetch permit-scoped leads for that geo

4. Fetch permit-scoped stats for that geo

5. Fetch active geo-scoped signals for that geo

6. Search geo-scoped signals across a state

Common first-run issues

​What you’ll build

​Prerequisites

​0. Set environment variables

​1. Resolve user input to geo_id

​2. Fetch permits for that geo

​3. Fetch permit-scoped leads for that geo

​4. Fetch permit-scoped stats for that geo

​5. Fetch active geo-scoped signals for that geo

​6. Search geo-scoped signals across a state

​Common first-run issues

What you’ll build

Prerequisites

0. Set environment variables

1. Resolve user input to `geo_id`

2. Fetch permits for that geo

3. Fetch permit-scoped leads for that geo

4. Fetch permit-scoped stats for that geo

5. Fetch active geo-scoped signals for that geo

6. Search geo-scoped signals across a state

Common first-run issues