canonical: https://jentic.com/apis/pharosdata.io/pharos

# Pharosdata Pharos API

Jentic publishes the only available OpenAPI specification for Pharos API, keeping it validated and agent-ready. The Pharos API provides an asynchronous interface for submitting geospatial data queries and checking their completion status. It uses a two-endpoint pattern: POST /async submits a query job and returns a job ID, while GET /check polls for completion and retrieves results. This enables processing of complex geospatial and analytics workloads without blocking on long-running computations.

## For AI agents

Submit asynchronous geospatial data queries and poll for results. The two-endpoint API handles long-running analytics jobs without blocking.

## Scope

Does not handle real-time streaming data, visualization rendering, or map tile serving - use for asynchronous geospatial data queries and batch analytics only.

## Capabilities

- Submit complex geospatial data queries for asynchronous processing
- Poll job status to determine when query results are ready
- Process large-scale geospatial analytics without request timeouts
- Retrieve computed results once async jobs complete

## Use cases

### Asynchronous Geospatial Analysis

Submit geospatial queries that require significant processing time without blocking the calling application. POST /async accepts query parameters and returns a job identifier immediately. Agents then poll GET /check with the job ID until results are ready. This pattern handles complex spatial computations, area aggregations, and multi-layer data intersections that would exceed synchronous request timeouts.

Example prompt: Submit a geospatial query via POST /async with area coordinates and data parameters, receive a job ID, then poll GET /check with the job ID until status shows completion

### Long-Running Data Pipeline Integration

Integrate Pharos into data pipelines where geospatial enrichment or analysis steps take variable time. The async pattern allows pipeline orchestrators to submit jobs, continue with other tasks, and retrieve results when ready. This decouples the pipeline execution from the query processing time, improving throughput and resilience.

Example prompt: Submit a batch of geospatial queries via POST /async for each dataset partition, track all job IDs, then collect results from GET /check as each completes

### AI Agent Geospatial Query via Jentic

AI agents submit and monitor geospatial data queries through Jentic without implementing async polling logic manually. Agents search for geospatial analysis capabilities, receive the two-step operation pattern (submit then check), and Jentic handles the async workflow coordination. This enables agents to incorporate geospatial intelligence into decision-making workflows.

Example prompt: Search Jentic for 'submit a geospatial data query', load the POST /async schema, execute with query parameters, then load GET /check and poll until results are available

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/async` | Submit a geospatial data query |
| GET | `/check` | Check query completion status |

## Key resources

- **Async Jobs** — Submit geospatial data queries for async processing
- **Status Checks** — Poll job completion and retrieve results

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 62 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 47 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 50 / 100
- **View full report:** https://jentic.com/apis/pharosdata.io/pharos/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Pharos API by hand means passing your key in the X-API-Key header on api.pharosdata.io, submitting async geospatial jobs, and polling for their completion yourself. Through Jentic you install once, import the Pharos API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** The Pharos API exposes POST /async to submit a query and GET /check to poll it, and both targets travel in the request or query rather than the URL path, so the honest control is operations-only: you limit the agent to the operations it needs, such as submitting a query and checking its status. You choose the operations it may call, so it is limited to that set.
- **Credential handling:** Your Pharos API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'run a geospatial batch query', and Jentic returns the matching Pharos operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **PostHog API** — PostHog provides product analytics that can be enriched with geospatial data from Pharos.
- **Mixpanel API** — Mixpanel handles event-based product analytics that can incorporate geospatial context from Pharos queries.
- **Amplitude API** — Amplitude provides behavioral analytics that can be augmented with geospatial intelligence from Pharos.

## FAQ

### Why is there no official OpenAPI spec for Pharos API?

Pharos Data does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Pharos API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Pharos API use?

The Pharos API uses an API key passed in the X-API-Key request header. Through Jentic, your API key is stored encrypted in the credential vault and agents receive scoped access without the raw key entering their context.

### How does the async query pattern work?

POST /async submits a geospatial query and immediately returns a job ID without waiting for results. GET /check accepts the job ID and returns the current status. Poll GET /check until the status indicates completion, then retrieve the results from the response body. This handles long-running queries without timeout issues.

### How do I submit a geospatial query through Jentic?

Search Jentic for 'submit a geospatial data query' to discover the POST /async operation. Load the schema to see required parameters (coordinates, data layers, query type), then execute. Use GET /check with the returned job ID to monitor progress and retrieve results.

### What happens if a query fails or times out?

GET /check returns the current job status including failure states. If a query fails, the status response includes error information. There is no server-side timeout on the async processing - jobs run to completion or failure, and you poll at your own pace.

### Can I limit what my agent is allowed to do with the Pharos API?

Yes. Because you run Jentic One yourself, your own rules decide which Pharos operations and credentials the agent can use, and the Pharos API has just two operations: POST /async to submit a geospatial query and GET /check to poll its status. Since the query target travels in the request or query rather than the URL path, the honest control here is operations-level: you can allow the agent to submit queries and check status, or restrict it to only checking status. Your stored API key is injected at execution time for the operations you permit and never enters the agent's prompt or context.