GMaps Lead Finder

https://gmapsleadfinder.com/docs
Admin
GMaps Lead Finder is a lead generation and scraping platform that extracts business data, reviews,...
Tokens:16,735
Snippets:120
Trust Score:5
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Example response for GET /api/v1/me

Source: https://gmapsleadfinder.com/docs/api

Example JSON response from the GET /api/v1/me endpoint showing a growth plan with 5000 credit limit, 120 used, and 4880 remaining.

```json
{
  "plan": "growth",
  "creditsLimit": 5000,
  "creditsUsed": 120,
  "creditsRemaining": 4880
}
```

--------------------------------

### Install and use .NET SDK (GmapsLeadFinder.GoogleMapsScraper)

Source: https://gmapsleadfinder.com/docs/sdk

Install the NuGet package and use the Client. The client reads GMF_API_KEY from the environment. The CLI is installed as a global tool and provides me and scrape commands.

```bash
dotnet add package GmapsLeadFinder.GoogleMapsScraper
dotnet tool install -g GmapsLeadFinder.GoogleMapsScraper.Cli
gmaps-scraper me
gmaps-scraper scrape "dentists in Austin TX" --out leads.json
```

```csharp
using GmapsLeadFinder.GoogleMapsScraper;

using var client = new Client(); // reads GMF_API_KEY
var rows = await client.ScrapeAsync("dentists in Austin TX");
Console.WriteLine(rows.Count);
```

--------------------------------

### Install and use Rust SDK (google-maps-scraper-sdk)

Source: https://gmapsleadfinder.com/docs/sdk

Install the Rust crate and use the Client. The client reads GMF_API_KEY from the environment. The CLI can be installed with cargo install.

```bash
cargo add google-maps-scraper-sdk
# CLI: cargo install google-maps-scraper-sdk --bin gmaps-scraper
```

```rust
use google_maps_scraper_sdk::{Client, ClientOptions};

let client = Client::new(ClientOptions::default())?; // reads GMF_API_KEY
let rows = client.scrape("dentists in Austin TX", Default::default())?;
println!("{} {:?}", rows.len(), rows.first());
```

--------------------------------

### Example response for Get photos job results

Source: https://gmapsleadfinder.com/docs/api

Example JSON response showing a completed job with one row of photo data, including the nextCursor value for pagination.

```json
{
  "jobId": "9f0e1d2c-3b4a-5987-6543-210fedcba987",
  "status": "completed",
  "columns": ["Photo URL", "Width", "Height"],
  "rows": [
    {
      "Photo URL": "https://lh3.googleusercontent.com/…=s1280-k-no",
      "Width": "1280",
      "Height": "960"
    }
  ],
  "count": 1,
  "total": 64,
  "cursor": 0,
  "nextCursor": "1"
}
```

--------------------------------

### Example response: Get photos job status

Source: https://gmapsleadfinder.com/docs/api

Example JSON response showing a completed job with 64 rows, no error, and 4636 credits remaining.

```json
{
  "id": "9f0e1d2c-3b4a-5987-6543-210fedcba987",
  "status": "completed",
  "rowCount": 64,
  "error": null,
  "createdAt": "2026-09-19T02:00:00.000Z",
  "finishedAt": "2026-09-19T02:02:15.000Z",
  "creditsRemaining": 4636
}
```

--------------------------------

### Install and use Go SDK (github.com/google-maps-lead-scraper/google-maps-scraper/go)

Source: https://gmapsleadfinder.com/docs/sdk

Install the Go module and use the Client. The client reads GMF_API_KEY from the environment. The CLI is run from the repo with go run ./cli scrape.

```bash
go get github.com/google-maps-lead-scraper/google-maps-scraper/go@v0.1.1
# CLI from the repo: cd go && go run ./cli scrape "dentists in Austin TX" --out leads.json
```

```go
import gmaps "github.com/google-maps-lead-scraper/google-maps-scraper/go"

client, _ := gmaps.NewClient(nil) // reads GMF_API_KEY
rows, _ := client.Scrape("dentists in Austin TX", nil)
fmt.Println(len(rows), rows[0])
```

--------------------------------

### Example response - Get job results

Source: https://gmapsleadfinder.com/docs/api

Shows a sample JSON response with job metadata, columns, and a single row. The nextCursor field is "1", indicating more pages are available.

```json
{
  "jobId": "3f2c8a1e-9b4d-4c2a-8e1f-0a1b2c3d4e5f",
  "status": "completed",
  "columns": ["Name", "Phone", "Website", "Emails"],
  "rows": [
    {
      "Name": "Austin Smile Dental",
      "Phone": "(512) 555-0142",
      "Website": "https://example.com",
      "Emails": "hello@example.com"
    }
  ],
  "count": 1,
  "total": 42,
  "cursor": 0,
  "nextCursor": "1"
}
```

--------------------------------

### Example response: Get job status

Source: https://gmapsleadfinder.com/docs/api

Example JSON response for a completed job. Shows the job metadata including status 'completed', keyword list, row count, per-keyword file record with page and row counts, and remaining credits.

```json
{
  "id": "3f2c8a1e-9b4d-4c2a-8e1f-0a1b2c3d4e5f",
  "status": "completed",
  "keywords": ["dentists in Austin TX"],
  "keywordCount": 1,
  "currentKeywordIndex": 0,
  "rowCount": 42,
  "error": null,
  "createdAt": "2026-09-13T01:00:00.000Z",
  "finishedAt": "2026-09-13T01:02:10.000Z",
  "files": [
    {
      "id": "…",
      "keyword": "dentists in Austin TX",
      "position": 0,
      "status": "completed",
      "pageCount": 3,
      "rowCount": 42,
      "enrichStatus": "completed",
      "error": null
    }
  ],
  "creditsRemaining": 4838
}
```

--------------------------------

### Authorization Header Example

Source: https://gmapsleadfinder.com/docs/agent

Example of the Authorization header format using your gmf_ key. Replace <your_key> with your actual key.

```http
Authorization: Bearer gmf_<your_key>
```

--------------------------------

### Install and use Ruby SDK (google-maps-scraper-sdk)

Source: https://gmapsleadfinder.com/docs/sdk

Install the Ruby gem and use the Client. The client reads GMF_API_KEY from the environment. The CLI commands check authentication and run a scrape, writing results to leads.json.

```bash
gem install google-maps-scraper-sdk
# or: bundle add google-maps-scraper-sdk
gmaps-scraper me
gmaps-scraper scrape "dentists in Austin TX" --out leads.json
```

```ruby
require "gmaps_scraper"

client = GmapsScraper::Client.new # reads GMF_API_KEY
rows = client.scrape("dentists in Austin TX")
puts rows.length
```

--------------------------------

### Install and use PHP SDK (gmapsleadfinder/google-maps-scraper)

Source: https://gmapsleadfinder.com/docs/sdk

Install the PHP package and use the Client. The client reads GMF_API_KEY from the environment. The CLI is available via vendor/bin/gmaps-scraper. The source lives in a separate repo: github.com/google-maps-lead-scraper/google-maps-scraper-php.

```bash
composer require gmapsleadfinder/google-maps-scraper
vendor/bin/gmaps-scraper me
vendor/bin/gmaps-scraper scrape "dentists in Austin TX" --out leads.json
```

```php
use GmapsLeadFinder\GoogleMapsScraper\Client;

$client = new Client(); // reads GMF_API_KEY
$rows = $client->scrape("dentists in Austin TX");
echo count($rows), "\n";
```

--------------------------------

### Example response: Get reviews job status

Source: https://gmapsleadfinder.com/docs/api

Shows a completed job response with id, status, rowCount, error, createdAt, finishedAt, and creditsRemaining fields.

```json
{
  "id": "7a1b2c3d-4e5f-6789-abcd-ef0123456789",
  "status": "completed",
  "rowCount": 128,
  "error": null,
  "createdAt": "2026-09-19T01:00:00.000Z",
  "finishedAt": "2026-09-19T01:03:40.000Z",
  "creditsRemaining": 4672
}
```

--------------------------------

### Install and use Python SDK (google-maps-scraper-sdk)

Source: https://gmapsleadfinder.com/docs/sdk

Install the Python package and run the CLI or use the Client class. The client reads GMF_API_KEY from the environment. The CLI command gmaps-scraper me checks authentication, and gmaps-scraper scrape runs a search and writes results to leads.json.

```bash
pip install google-maps-scraper-sdk
gmaps-scraper me
gmaps-scraper scrape "dentists in Austin TX" --out leads.json
# or: python -m gmaps_scraper me
```

```python
from gmaps_scraper import Client

client = Client()  # reads GMF_API_KEY
rows = client.scrape("dentists in Austin TX")
print(len(rows), rows[0] if rows else None)
```

--------------------------------

### Example response for review job results

Source: https://gmapsleadfinder.com/docs/api

Example JSON response showing the structure of the returned data, including columns, rows, pagination fields, and nextCursor.

```json
{
  "jobId": "7a1b2c3d-4e5f-6789-abcd-ef0123456789",
  "status": "completed",
  "columns": ["Rating", "Text", "User", "Date"],
  "rows": [
    {
      "Rating": "5",
      "Text": "Great visit.",
      "User": "Alex",
      "Date": "2026-08-01"
    }
  ],
  "count": 1,
  "total": 128,
  "cursor": 0,
  "nextCursor": "1"
}
```

--------------------------------

### Install and use TypeScript/Node SDK (@gmapsleadfinder/google-maps-scraper)

Source: https://gmapsleadfinder.com/docs/sdk

Install the npm package and use the CLI or the Client class. The client reads GMF_API_KEY from the environment. The CLI commands check authentication and run a scrape, writing results to leads.json.

```bash
npm install @gmapsleadfinder/google-maps-scraper
npx gmaps-scraper me
npx gmaps-scraper scrape "dentists in Austin TX" --out leads.json
```

```ts
import { Client } from "@gmapsleadfinder/google-maps-scraper";

const client = new Client(); // reads GMF_API_KEY
const rows = await client.scrape("dentists in Austin TX");
console.log(rows.length, rows[0]);
```

--------------------------------

### Example response for POST /api/v1/jobs

Source: https://gmapsleadfinder.com/docs/api

Example JSON response from the POST /api/v1/jobs endpoint showing a jobId, keywordCount of 1, and creditsRemaining of 4880.

```json
{
  "jobId": "3f2c8a1e-9b4d-4c2a-8e1f-0a1b2c3d4e5f",
  "keywordCount": 1,
  "creditsRemaining": 4880
}
```

--------------------------------

### Get plan & credits with curl

Source: https://gmapsleadfinder.com/docs/api

Use this curl command to call GET /api/v1/me. It requires a Bearer token from the GMF_API_KEY environment variable. The response includes plan, creditsLimit, creditsUsed, and creditsRemaining.

```bash
curl -sS https://gmapsleadfinder.com/api/v1/me \
  -H "Authorization: Bearer $GMF_API_KEY"
```

--------------------------------

### GET /api/v1/me

Source: https://gmapsleadfinder.com/docs/api

Retrieves the current user's account information, including the remaining credits. This is used to confirm that creditsRemaining is greater than 0 before starting a job.

```APIDOC
## GET /api/v1/me

### Description
Retrieves the current user's account information, including the remaining credits. This is used to confirm that creditsRemaining is greater than 0 before starting a job.

### Method
GET

### Endpoint
/api/v1/me

### Response
#### Success Response (200)
- **creditsRemaining** (number) - The number of credits remaining for the user.

#### Response Example
{
  "creditsRemaining": 100
}
```

--------------------------------

### Example response for create reviews job

Source: https://gmapsleadfinder.com/docs/api

Example JSON response from the POST /api/v1/review-jobs endpoint. Contains jobId (uuid) and creditsRemaining (number).

```json
{
  "jobId": "7a1b2c3d-4e5f-6789-abcd-ef0123456789",
  "creditsRemaining": 4800
}
```

--------------------------------

### Get plan & credits with JavaScript fetch

Source: https://gmapsleadfinder.com/docs/api

Use this JavaScript snippet to call GET /api/v1/me using fetch. It reads the API key from the GMF_API_KEY environment variable and logs the creditsRemaining field from the JSON response.

```js
const res = await fetch("https://gmapsleadfinder.com/api/v1/me", {
  headers: { Authorization: `Bearer ${process.env.GMF_API_KEY}` },
});
const me = await res.json();
console.log(me.creditsRemaining);
```

--------------------------------

### GET /api/v1/me

Source: https://gmapsleadfinder.com/docs/api

Retrieves information about the authenticated user. This endpoint is used to verify the API key and get account details.

```APIDOC
## GET /api/v1/me

### Description
Retrieves information about the authenticated user. This endpoint is used to verify the API key and get account details.

### Method
GET

### Endpoint
/api/v1/me

### Authentication
Requires Authorization header with Bearer token (gmf_...).

### Response
#### Success Response (200)
- **user** (object) - The authenticated user's details.

#### Response Example
{
  "user": {}
}
```

--------------------------------

### GET /api/v1/me

Source: https://gmapsleadfinder.com/docs/api

Returns the authenticated user's plan and credit snapshot. Useful before creating jobs.

```APIDOC
## GET /api/v1/me

### Description
Returns the authenticated user's plan and credit snapshot. Useful before creating jobs.

### Method
GET

### Endpoint
/api/v1/me

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Bearer gmf_… API key

### Response
#### Success Response (200)
- **plan** (string) - Plan id / name for the account
- **creditsLimit** (number) - Credit limit for the current period (or lifetime free pool)
- **creditsUsed** (number) - Credits already consumed
- **creditsRemaining** (number) - creditsLimit − creditsUsed

#### Response Example
{
  "plan": "growth",
  "creditsLimit": 5000,
  "creditsUsed": 120,
  "creditsRemaining": 4880
}

### Error Codes
- 401 — Missing or invalid API key
- 403 — Key valid but plan cannot use the agent API

```

--------------------------------

### curl: Get reviews job status

Source: https://gmapsleadfinder.com/docs/api

Sends a GET request to /api/v1/review-jobs/$JOB_ID with Bearer authentication. Requires the job ID from POST /api/v1/review-jobs and the GMF_API_KEY environment variable.

```bash
curl -sS https://gmapsleadfinder.com/api/v1/review-jobs/$JOB_ID \
  -H "Authorization: Bearer $GMF_API_KEY"
```

--------------------------------

### Example response for create photos job

Source: https://gmapsleadfinder.com/docs/api

Shows the JSON response containing a jobId (uuid) for polling and creditsRemaining after queueing. Credits are consumed as unique photo URLs are collected.

```json
{
  "jobId": "9f0e1d2c-3b4a-5987-6543-210fedcba987",
  "creditsRemaining": 4700
}

```

--------------------------------

### GET /api/v1/jobs/{id}/results

Source: https://gmapsleadfinder.com/docs/api

Retrieves the results of a leads job. The response includes a nextCursor for pagination; follow it until null.

```APIDOC
## GET /api/v1/jobs/{id}/results

### Description
Retrieves the results of a leads job. The response includes a nextCursor for pagination; follow it until null.

### Method
GET

### Endpoint
/api/v1/jobs/{id}/results

### Parameters
#### Path Parameters
- **id** (string) - Required - The job ID returned from the POST request.

### Response
#### Success Response (200)
- **nextCursor** (string or null) - The cursor for the next page of results, or null if there are no more results.

#### Response Example
{
  "nextCursor": "abc123"
}
```

--------------------------------

### Claude Code MCP Install Command

Source: https://gmapsleadfinder.com/docs/agent

Command to add the Remote MCP server to Claude Code. Uses gmf_YOUR_API_KEY as a placeholder until you sign in and copy your key.

```bash
claude mcp add --transport http gmaps-finder https://gmapsleadfinder.com/mcp \
  --header "Authorization: Bearer gmf_YOUR_API_KEY"
```

--------------------------------

### GET /api/v1/photo-jobs/{id}/results

Source: https://gmapsleadfinder.com/docs/api

Retrieves the results of a photos job. The response includes a nextCursor for pagination; follow it until null.

```APIDOC
## GET /api/v1/photo-jobs/{id}/results

### Description
Retrieves the results of a photos job. The response includes a nextCursor for pagination; follow it until null.

### Method
GET

### Endpoint
/api/v1/photo-jobs/{id}/results

### Parameters
#### Path Parameters
- **id** (string) - Required - The job ID returned from the POST request.

### Response
#### Success Response (200)
- **nextCursor** (string or null) - The cursor for the next page of results, or null if there are no more results.

#### Response Example
{
  "nextCursor": "abc123"
}
```

--------------------------------

### GET /api/v1/review-jobs/{id}/results

Source: https://gmapsleadfinder.com/docs/api

Retrieves the results of a reviews job. The response includes a nextCursor for pagination; follow it until null.

```APIDOC
## GET /api/v1/review-jobs/{id}/results

### Description
Retrieves the results of a reviews job. The response includes a nextCursor for pagination; follow it until null.

### Method
GET

### Endpoint
/api/v1/review-jobs/{id}/results

### Parameters
#### Path Parameters
- **id** (string) - Required - The job ID returned from the POST request.

### Response
#### Success Response (200)
- **nextCursor** (string or null) - The cursor for the next page of results, or null if there are no more results.

#### Response Example
{
  "nextCursor": "abc123"
}
```

--------------------------------

### curl - Get job results

Source: https://gmapsleadfinder.com/docs/api

Fetches the first page of job results using a Bearer token. Requires the GMF_API_KEY environment variable and a valid JOB_ID. The limit parameter is set to 100.

```bash
curl -sS "https://gmapsleadfinder.com/api/v1/jobs/$JOB_ID/results?limit=100" \
  -H "Authorization: Bearer $GMF_API_KEY"
```

--------------------------------

### GET /api/v1/jobs/{id}

Source: https://gmapsleadfinder.com/docs/api

Polls the status of a leads job. The status can be completed, partial, or failed.

```APIDOC
## GET /api/v1/jobs/{id}

### Description
Polls the status of a leads job. The status can be completed, partial, or failed.

### Method
GET

### Endpoint
/api/v1/jobs/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The job ID returned from the POST request.

### Response
#### Success Response (200)
- **status** (string) - The status of the job: completed, partial, or failed.

#### Response Example
{
  "status": "completed"
}
```

--------------------------------

### GET /api/v1/photo-jobs/{id}

Source: https://gmapsleadfinder.com/docs/api

Polls the status of a photos job. The status can be completed, partial, or failed.

```APIDOC
## GET /api/v1/photo-jobs/{id}

### Description
Polls the status of a photos job. The status can be completed, partial, or failed.

### Method
GET

### Endpoint
/api/v1/photo-jobs/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The job ID returned from the POST request.

### Response
#### Success Response (200)
- **status** (string) - The status of the job: completed, partial, or failed.

#### Response Example
{
  "status": "completed"
}
```

--------------------------------

### JavaScript: Get reviews job status

Source: https://gmapsleadfinder.com/docs/api

Fetches the job status using fetch with Bearer token from process.env.GMF_API_KEY. Parses the JSON response into the job object.

```js
const res = await fetch(`https://gmapsleadfinder.com/api/v1/review-jobs/${jobId}`, {
  headers: { Authorization: `Bearer ${process.env.GMF_API_KEY}` },
});
const job = await res.json();
```

--------------------------------

### GET /api/v1/review-jobs/{id}/results

Source: https://gmapsleadfinder.com/docs/api

Returns paginated review rows as JSON objects keyed by export column headers. Follow nextCursor until null. Column set matches Reviews export preferences.

```APIDOC
## GET /api/v1/review-jobs/{id}/results

### Description
Returns paginated review rows as JSON objects keyed by export column headers. Follow nextCursor until null. Column set matches Reviews export preferences.

### Method
GET

### Endpoint
/api/v1/review-jobs/{id}/results

### Parameters
#### Path Parameters
- **id** (string uuid) - Required - Reviews job id

#### Query Parameters
- **limit** (integer) - Optional - Page size 1-500 (default 100)
- **cursor** (string) - Optional - Offset cursor from a previous nextCursor (default 0)

#### Header Parameters
- **Authorization** (string) - Required - Bearer gmf_... API key

### Request Example
curl -sS "https://gmapsleadfinder.com/api/v1/review-jobs/$JOB_ID/results?limit=100" \
  -H "Authorization: Bearer $GMF_API_KEY"

### Response
#### Success Response (200)
- **jobId** (string) - Job id
- **status** (string) - Current job status
- **columns** (string[]) - Ordered export column headers
- **rows** (object[]) - Each row is { [column]: string }
- **count** (number) - Rows in this page
- **total** (number) - Total rows available for the job
- **cursor** (number) - Offset used for this page
- **nextCursor** (string | null) - Pass as cursor for the next page; null when done

#### Response Example
{
  "jobId": "7a1b2c3d-4e5f-6789-abcd-ef0123456789",
  "status": "completed",
  "columns": ["Rating", "Text", "User", "Date"],
  "rows": [
    {
      "Rating": "5",
      "Text": "Great visit.",
      "User": "Alex",
      "Date": "2026-08-01"
    }
  ],
  "count": 1,
  "total": 128,
  "cursor": 0,
  "nextCursor": "1"
}

### Error Codes
- **400** - Not a reviews job
- **401** - Missing or invalid API key
- **403** - Plan cannot use the agent API
- **404** - Job not found
```

--------------------------------

### GET /api/v1/jobs/{id}

Source: https://gmapsleadfinder.com/docs/api

Polls job metadata until the job status is completed, partial, or failed. Includes per-keyword file progress when available.

```APIDOC
## GET /api/v1/jobs/{id}

### Description
Polls job metadata until the job status is completed, partial, or failed. Includes per-keyword file progress when available.

### Method
GET

### Endpoint
/api/v1/jobs/{id}

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Bearer gmf_… API key

#### Path Parameters
- **id** (string uuid) - Required - Job id returned by POST /api/v1/jobs

### Response
#### Success Response (200)
- **id** (string) - Job id
- **status** (string) - queued | running | completed | partial | failed (and related pipeline states)
- **keywords** (string[]) - Keyword list for the job
- **keywordCount** (number) - Number of keywords
- **currentKeywordIndex** (number) - Progress index while running
- **rowCount** (number) - Rows collected so far / total for the job
- **error** (string | null) - Error message when failed
- **createdAt** (string ISO) - Created timestamp
- **finishedAt** (string | null) - Finished timestamp
- **files** (object[]) - Per-keyword file records: id, keyword, position, status, pageCount, rowCount, enrichStatus, error
- **creditsRemaining** (number) - Current credits remaining

#### Response Example
{
  "id": "3f2c8a1e-9b4d-4c2a-8e1f-0a1b2c3d4e5f",
  "status": "completed",
  "keywords": ["dentists in Austin TX"],
  "keywordCount": 1,
  "currentKeywordIndex": 0,
  "rowCount": 42,
  "error": null,
  "createdAt": "2026-09-13T01:00:00.000Z",
  "finishedAt": "2026-09-13T01:02:10.000Z",
  "files": [
    {
      "id": "…",
      "keyword": "dentists in Austin TX",
      "position": 0,
      "status": "completed",
      "pageCount": 3,
      "rowCount": 42,
      "enrichStatus": "completed",
      "error": null
    }
  ],
  "creditsRemaining": 4838
}

### Error Codes
- **401** - Missing or invalid API key
- **403** - Plan cannot use the agent API
- **404** - Job not found for this key’s user

### curl Example
```bash
curl -sS https://gmapsleadfinder.com/api/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $GMF_API_KEY"
```

### JavaScript Example
```js
const res = await fetch(`https://gmapsleadfinder.com/api/v1/jobs/${jobId}`, {
  headers: { Authorization: `Bearer ${process.env.GMF_API_KEY}` },
});
const job = await res.json();
// poll while job.status is queued or running
```
```

--------------------------------

### curl: Get review job results

Source: https://gmapsleadfinder.com/docs/api

Use this curl command to fetch review job results. Replace $JOB_ID with the job ID and $GMF_API_KEY with your API key. The limit parameter is optional (default 100).

```bash
curl -sS "https://gmapsleadfinder.com/api/v1/review-jobs/$JOB_ID/results?limit=100" \
  -H "Authorization: Bearer $GMF_API_KEY"
```

--------------------------------

### GET /api/v1/review-jobs/{id}

Source: https://gmapsleadfinder.com/docs/api

Retrieves the status and metadata of a reviews job. Poll this endpoint until the status is completed, partial, or failed.

```APIDOC
## GET /api/v1/review-jobs/{id}

### Description
Retrieves the status and metadata of a reviews job. Poll this endpoint until the status is completed, partial, or failed.

### Method
GET

### Endpoint
/api/v1/review-jobs/{id}

### Parameters
#### Path Parameters
- **id** (string uuid) - Required - Job id returned by POST /api/v1/review-jobs

#### Header Parameters
- **Authorization** (string) - Required - Bearer gmf_... API key

### Response
#### Success Response (200)
- **id** (string) - Job id
- **status** (string) - queued | running | completed | partial | failed (and related pipeline states)
- **rowCount** (number) - Review rows collected so far / total
- **error** (string | null) - Error message when failed
- **createdAt** (string ISO) - Created timestamp
- **finishedAt** (string | null) - Finished timestamp
- **creditsRemaining** (number) - Current credits remaining

#### Response Example
{
  "id": "7a1b2c3d-4e5f-6789-abcd-ef0123456789",
  "status": "completed",
  "rowCount": 128,
  "error": null,
  "createdAt": "2026-09-19T01:00:00.000Z",
  "finishedAt": "2026-09-19T01:03:40.000Z",
  "creditsRemaining": 4672
}

### Error Codes
- 400 - Job exists but is not a reviews job
- 401 - Missing or invalid API key
- 403 - Plan cannot use the agent API
- 404 - Job not found for this key's user

### curl Example
```bash
curl -sS https://gmapsleadfinder.com/api/v1/review-jobs/$JOB_ID \
  -H "Authorization: Bearer $GMF_API_KEY"
```

### JavaScript Example
```js
const res = await fetch(`https://gmapsleadfinder.com/api/v1/review-jobs/${jobId}`, {
  headers: { Authorization: `Bearer ${process.env.GMF_API_KEY}` },
});
const job = await res.json();
```
```

--------------------------------

### Get photos job results with curl

Source: https://gmapsleadfinder.com/docs/api

Use this curl command to fetch a page of photo results. Replace $JOB_ID and $GMF_API_KEY with your job ID and API key. The limit parameter is set to 100.

```bash
curl -sS "https://gmapsleadfinder.com/api/v1/photo-jobs/$JOB_ID/results?limit=100" \
  -H "Authorization: Bearer $GMF_API_KEY"
```

--------------------------------

### GET /api/v1/jobs/{id}/results

Source: https://gmapsleadfinder.com/docs/api

Returns paginated place rows as JSON objects keyed by export column headers. Follow nextCursor until null. Column set matches Leads export-column preferences.

```APIDOC
## GET /api/v1/jobs/{id}/results

### Description
Returns paginated place rows as JSON objects keyed by export column headers. Follow nextCursor until null. Column set matches Leads export-column preferences.

### Method
GET

### Endpoint
/api/v1/jobs/{id}/results

### Parameters
#### Path Parameters
- **id** (string uuid) - Required - Job id

#### Query Parameters
- **limit** (integer) - Optional - Page size 1-500 (default 100)
- **cursor** (string) - Optional - Offset cursor from a previous nextCursor (default 0)

#### Request Headers
- **Authorization** (string) - Required - Bearer gmf_... API key

### Request Example
curl -sS "https://gmapsleadfinder.com/api/v1/jobs/$JOB_ID/results?limit=100" \
  -H "Authorization: Bearer $GMF_API_KEY"

### Response
#### Success Response (200)
- **jobId** (string) - Job id
- **status** (string) - Current job status
- **columns** (string[]) - Ordered export column headers
- **rows** (object[]) - Each row is { [column]: string }
- **count** (number) - Rows in this page
- **total** (number) - Total rows available for the job
- **cursor** (number) - Offset used for this page
- **nextCursor** (string | null) - Pass as cursor for the next page; null when done

#### Response Example
{
  "jobId": "3f2c8a1e-9b4d-4c2a-8e1f-0a1b2c3d4e5f",
  "status": "completed",
  "columns": ["Name", "Phone", "Website", "Emails"],
  "rows": [
    {
      "Name": "Austin Smile Dental",
      "Phone": "(512) 555-0142",
      "Website": "https://example.com",
      "Emails": "hello@example.com"
    }
  ],
  "count": 1,
  "total": 42,
  "cursor": 0,
  "nextCursor": "1"
}

### Error codes
- 401 - Missing or invalid API key
- 403 - Plan cannot use the agent API
- 404 - Job not found
```

--------------------------------

### GET /api/v1/photo-jobs/{id}/results

Source: https://gmapsleadfinder.com/docs/api

Retrieves paginated photo URL results for a specific photos job. Use the nextCursor value from the response to fetch subsequent pages until null.

```APIDOC
## GET /api/v1/photo-jobs/{id}/results

### Description
Returns paginated photo URL rows as JSON objects keyed by export column headers. Follow nextCursor until null. Column set matches Photos export preferences. Unique photo URLs are billed 1 credit each after dedupe.

### Method
GET

### Endpoint
https://gmapsleadfinder.com/api/v1/photo-jobs/{id}/results

### Parameters
#### Path Parameters
- **id** (string uuid) - Required - Photos job id

#### Query Parameters
- **limit** (integer) - Optional - Page size 1-500 (default 100)
- **cursor** (string) - Optional - Offset cursor from a previous nextCursor (default 0)

#### Headers
- **Authorization** (string) - Required - Bearer gmf_... API key

### Request Example
curl -sS "https://gmapsleadfinder.com/api/v1/photo-jobs/$JOB_ID/results?limit=100" \
  -H "Authorization: Bearer $GMF_API_KEY"

### Response
#### Success Response (200)
- **jobId** (string) - Job id
- **status** (string) - Current job status
- **columns** (string[]) - Ordered export column headers
- **rows** (object[]) - Each row is { [column]: string }
- **count** (number) - Rows in this page
- **total** (number) - Total rows available for the job
- **cursor** (number) - Offset used for this page
- **nextCursor** (string | null) - Pass as cursor for the next page; null when done

#### Response Example
{
  "jobId": "9f0e1d2c-3b4a-5987-6543-210fedcba987",
  "status": "completed",
  "columns": ["Photo URL", "Width", "Height"],
  "rows": [
    {
      "Photo URL": "https://lh3.googleusercontent.com/...=s1280-k-no",
      "Width": "1280",
      "Height": "960"
    }
  ],
  "count": 1,
  "total": 64,
  "cursor": 0,
  "nextCursor": "1"
}

### Error Codes
- **400** - Not a photos job
- **401** - Missing or invalid API key
- **403** - Plan cannot use the agent API
- **404** - Job not found
```

--------------------------------

### GET /api/v1/photo-jobs/{id}

Source: https://gmapsleadfinder.com/docs/api

Retrieves the current status and metadata of a photos job. Use this endpoint to poll the job until its status becomes completed, partial, or failed.

```APIDOC
## GET /api/v1/photo-jobs/{id}

### Description
Retrieves the current status and metadata of a photos job. Use this endpoint to poll the job until its status becomes completed, partial, or failed.

### Method
GET

### Endpoint
/api/v1/photo-jobs/{id}

### Parameters
#### Path Parameters
- **id** (string uuid) - Required - Job id returned by POST /api/v1/photo-jobs

#### Header Parameters
- **Authorization** (string) - Required - Bearer gmf_... API key

### Request Example
curl -sS https://gmapsleadfinder.com/api/v1/photo-jobs/$JOB_ID \
  -H "Authorization: Bearer $GMF_API_KEY"

### Response
#### Success Response (200)
- **id** (string) - Job id
- **status** (string) - queued | running | completed | partial | failed (and related pipeline states)
- **rowCount** (number) - Photo URL rows collected so far / total
- **error** (string | null) - Error message when failed
- **createdAt** (string ISO) - Created timestamp
- **finishedAt** (string | null) - Finished timestamp
- **creditsRemaining** (number) - Current credits remaining

#### Response Example
{
  "id": "9f0e1d2c-3b4a-5987-6543-210fedcba987",
  "status": "completed",
  "rowCount": 64,
  "error": null,
  "createdAt": "2026-09-19T02:00:00.000Z",
  "finishedAt": "2026-09-19T02:02:15.000Z",
  "creditsRemaining": 4636
}

### Error Codes
- 400 - Job exists but is not a photos job
- 401 - Missing or invalid API key
- 403 - Plan cannot use the agent API
- 404 - Job not found for this key's user
```

--------------------------------

### Get photos job results with JavaScript fetch

Source: https://gmapsleadfinder.com/docs/api

Use this JavaScript code to fetch a page of photo results using the fetch API. It reads the API key from the GMF_API_KEY environment variable and parses the JSON response.

```js
const res = await fetch(`https://gmapsleadfinder.com/api/v1/photo-jobs/${jobId}/results?limit=100`, {
  headers: { Authorization: `Bearer ${process.env.GMF_API_KEY}` },
});
const page = await res.json();
```

--------------------------------

### JavaScript: Get photos job status

Source: https://gmapsleadfinder.com/docs/api

Use this JavaScript fetch call to retrieve the job status. It uses the jobId variable and the GMF_API_KEY environment variable. The response is parsed as JSON and stored in the job variable.

```js
const res = await fetch(`https://gmapsleadfinder.com/api/v1/photo-jobs/${jobId}`, {
  headers: { Authorization: `Bearer ${process.env.GMF_API_KEY}` },
});
const job = await res.json();
```

--------------------------------

### Set GMF_API_KEY environment variable

Source: https://gmapsleadfinder.com/docs/sdk

Required before using any SDK. The key is obtained from Account → API key after signing in on a Growth+ plan.

```bash
export GMF_API_KEY=gmf_your_key_here
```

--------------------------------

### JavaScript - Fetch all rows with pagination

Source: https://gmapsleadfinder.com/docs/api

Pagination loop that follows nextCursor until null, collecting all rows. Uses the GMF_API_KEY environment variable for authorization. The function returns an array of all rows across pages.

```js
async function fetchAllRows(jobId) {
  const rows = [];
  let cursor = "0";
  while (cursor != null) {
    const url = new URL(`https://gmapsleadfinder.com/api/v1/jobs/${jobId}/results`);
    url.searchParams.set("limit", "100");
    url.searchParams.set("cursor", cursor);
    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.GMF_API_KEY}` },
    });
    const page = await res.json();
    rows.push(...page.rows);
    cursor = page.nextCursor;
  }
  return rows;
}
```

--------------------------------

### JavaScript: Get job status

Source: https://gmapsleadfinder.com/docs/api

Use this JavaScript snippet to fetch job status using the Fetch API. It sends a GET request with the Authorization header and parses the JSON response. The comment indicates you should poll while the job status is 'queued' or 'running'.

```js
const res = await fetch(`https://gmapsleadfinder.com/api/v1/jobs/${jobId}`, {
  headers: { Authorization: `Bearer ${process.env.GMF_API_KEY}` },
});
const job = await res.json();
// poll while job.status is queued or running
```

--------------------------------

### Create a job with curl

Source: https://gmapsleadfinder.com/docs/api

Use this curl command to POST /api/v1/jobs with a single keyword. It requires a Bearer token and a JSON body with the keyword field. The response includes a jobId and creditsRemaining.

```bash
curl -sS -X POST https://gmapsleadfinder.com/api/v1/jobs \
  -H "Authorization: Bearer $GMF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"dentists in Austin TX"}'
```

--------------------------------

### Create a reviews job with curl

Source: https://gmapsleadfinder.com/docs/api

Use this curl command to POST a new review job. Requires an API key in the Authorization header and a place URL or business_id in the JSON body. Returns a jobId for polling and creditsRemaining.

```bash
curl -sS -X POST https://gmapsleadfinder.com/api/v1/review-jobs \
  -H "Authorization: Bearer $GMF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"place":"https://maps.google.com/?cid=…"}'
```

--------------------------------

### GET /api/v1/review-jobs/{id}

Source: https://gmapsleadfinder.com/docs/api

Polls the status of a reviews job. The status can be completed, partial, or failed.

```APIDOC
## GET /api/v1/review-jobs/{id}

### Description
Polls the status of a reviews job. The status can be completed, partial, or failed.

### Method
GET

### Endpoint
/api/v1/review-jobs/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The job ID returned from the POST request.

### Response
#### Success Response (200)
- **status** (string) - The status of the job: completed, partial, or failed.

#### Response Example
{
  "status": "completed"
}
```

--------------------------------

### Create a reviews job with JavaScript fetch

Source: https://gmapsleadfinder.com/docs/api

Use this JavaScript code to POST a new review job using fetch. Requires an API key in the Authorization header and a place URL or business_id in the JSON body. Returns a jobId for polling and creditsRemaining.

```js
const res = await fetch("https://gmapsleadfinder.com/api/v1/review-jobs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GMF_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ place: "https://maps.google.com/?cid=…" }),
});
const { jobId } = await res.json();
```

--------------------------------

### Create photos job with JavaScript fetch

Source: https://gmapsleadfinder.com/docs/api

Uses the Fetch API to POST a place to /api/v1/photo-jobs with an Authorization header and JSON body. The response is parsed to extract the jobId.

```js
const res = await fetch("https://gmapsleadfinder.com/api/v1/photo-jobs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GMF_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ place: "ChIJ…" }),
});
const { jobId } = await res.json();

```

--------------------------------

### Create a job with JavaScript fetch

Source: https://gmapsleadfinder.com/docs/api

Use this JavaScript snippet to POST /api/v1/jobs with a single keyword. It sends a JSON body with the keyword field and reads the jobId from the response.

```js
const res = await fetch("https://gmapsleadfinder.com/api/v1/jobs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GMF_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ keyword: "dentists in Austin TX" }),
});
const { jobId } = await res.json();
```

--------------------------------

### Create photos job with curl

Source: https://gmapsleadfinder.com/docs/api

Sends a POST request to /api/v1/photo-jobs with a Bearer API key and a JSON body containing the place. Requires exactly one place identifier; returns 409 if another job is running.

```bash
curl -sS -X POST https://gmapsleadfinder.com/api/v1/photo-jobs \
  -H "Authorization: Bearer $GMF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"place":"ChIJ…"}'

```

--------------------------------

### JavaScript: Fetch review job results

Source: https://gmapsleadfinder.com/docs/api

Use this JavaScript snippet to fetch review job results using the Fetch API. It uses the GMF_API_KEY environment variable for authorization.

```js
const res = await fetch(`https://gmapsleadfinder.com/api/v1/review-jobs/${jobId}/results?limit=100`, {
  headers: { Authorization: `Bearer ${process.env.GMF_API_KEY}` },
});
const page = await res.json();
```
Tokens:
Raw