Getting Started

The GeoLayer API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

Authentication

The GeoLayer API uses API keys to authenticate requests. You can view and manage your API keys in the GeoLayer Dashboard.

Authorization: Bearer YOUR_API_KEY

Rate Limits

Rate limits are applied based on your subscription tier. If you exceed the rate limit, the API will return a 429 Too Many Requests error.

Tier Burst Limit Daily Limit
Startup 10 req/sec 5,000 req/day
Growth 50 req/sec 25,000 req/day

Error Codes

GeoLayer uses conventional HTTP response codes to indicate the success or failure of an API request.

200 OK: Everything worked as expected.
500 Request Failed: Something went wrong, time to debug.
429 Too Many Requests: You have hit your rate limit.

Webhooks

Receive real-time notifications when your search tasks are complete. Set your Webhook URL in the Account Settings.

Payload Format

{
"event": "task.completed",
"submission_id": "job_12345",
"total_leads": 10
}
POST

Submit a Search Task

/v1/tasks/submit

Initializes a new search job. This endpoint returns a submission_id immediately. Use this ID to poll for results. Note: Upto 20 new leads are returned per task. Make sure you have Credits available.

Request Body (JSON)

keyword "Plumbers" The business niche.
city "Austin" The target location.

Response

  • submission_id: Unique ID for you to save to pull results later.
  • status: One of [queued, processing, completed, out_of_credits, error].
GET

Fetch Task Results

/v1/tasks/results/{submission_id}

Retrieves the collected data once the task is complete. If the task is still running, the status will return as "processing".

Response

  • status: One of [queued, processing, completed, error].
  • data: An array containing leads [first_name, last_name, email, phone, company_name, title, website, address, city, state, country_code etc.].
GET

Get Profile Data

/v1/get-user-data

Retrieves your profile and account data.

Response

  • full_name: Your name.
  • email: Your profile email.
  • credits_remaining: Your remaining credits count.
  • plan_name: Your monthly subscription plan name.
1. Submit Request 
curl -X POST "https://geolayer.io/v1/tasks/submit" \
  -d '{
    "keyword": "Plumbers",
    "city": "San Jose"
  }'

// Response
{
  "submission_id": "job_8291x_q",
  "status": "queued"
}
2. Fetch Results 
curl -X GET "https://geolayer.io/v1/tasks/results/job_8291x_q"

// Response
{
  "status": "completed",
  "data": [
    {
      "first_name": "John",
      "last_name": "Smith",
      "email": "info@draindoc.com",
      "phone": "+1-408-555-1234",
      "company_name": "Drain Doctor",
      "title": "Owner",
      "website": "https://www.draindoc.com",
      "address": "1234 Elm Street",
      "city": "San Jose",
      "state": "CA",
      "country_code": "US",
      "verified": true
    }
  ]
}

3. Get Profile Data 
curl -X GET "https://geolayer.io/v1/get-user-data"

// Response
{
  "full_name": "Tom Harrison",
  "email": "tom.harrisson75@gmail.com",
  "credits_remaining": 1000,
  "plan_name": "Growth"
}