Documentation / Spatial analysis, pipelines and result handles
Spatial analysis, pipelines and result handles
Measure and transform geometry, execute multi-step pipelines, and pass result handles between API operations.
On this page
Buffer a point and run a spatial pipeline
POST an operation to /analyze with the primary geometry in a and, where required, a second geometry in b. Inputs support GeoJSON, [longitude, latitude] pairs, Overpass responses, and result handles.
Available operations include buffer, centroid, bbox, area, length, distance, intersect, union, difference, contains, intersects, nearest, simplify, and convex. Use /compute for dependent operations that reference earlier results by step ID. Replace the example rh_ value with a handle returned by your own request.
curl --fail-with-body -X POST https://api.mapsource.io/analyze \
-H "Authorization: Bearer $MAPSOURCE_API_KEY" -H 'content-type: application/json' -d '{
"operation": "buffer",
"a": [-122.3321, 47.6062],
"distance": 500
}'
# Several steps in one call, referencing each other by id
curl --fail-with-body -X POST https://api.mapsource.io/compute \
-H "Authorization: Bearer $MAPSOURCE_API_KEY" -H 'content-type: application/json' -d '{
"pipeline": [
{"id":"hospitals","op":"nearby","args":{"lat":47.6062,"lon":-122.3321,"category":"hospital","radius":3000}},
{"id":"ranked","op":"sort","args":{"input":"$hospitals","by":"distanceMeters"}},
{"id":"closest","op":"limit","args":{"input":"$ranked","count":5}}
],
"return": "$closest"
}'
# Analyse a held query result by its handle
curl --fail-with-body -X POST https://api.mapsource.io/analyze \
-H "Authorization: Bearer $MAPSOURCE_API_KEY" -H 'content-type: application/json' -d '{
"operation": "convex",
"a": "rh_c44e50b878b3e87a15a2d5ec9f21b640"
}'Endpoints and parameters
Select an endpoint for its full parameter and response reference.
| Operation | Endpoint |
|---|---|
| Run a spatial analysis | POST /api/analyze |
| Run a multi-step spatial pipeline | POST /api/compute |
| Retrieve a held result | GET /api/results/{id} |
Application integration
GeoJSON coordinates use longitude, latitude order. Provide polygon geometry for overlay operations and specify distance units for buffers and simplification.
Assign each pipeline step a unique ID. Reference earlier outputs with $stepId and select the final output with return. Use estimateOnly before execution when a cost estimate is required.
Pass result handles directly to compatible operations. Download payloads that must outlive the handle's expiry, and regenerate expired intermediate results before continuing a workflow.
Access and limits
Pipelines support up to 12 steps. References use $stepId and must refer to an earlier step. Duplicate IDs, invalid references, incompatible inputs, and costs above the synchronous limit return HTTP 422 before execution. Set estimateOnly to true to calculate cost without running the pipeline.
Buffer radius and simplify tolerance are limited to 500 km. Feature collections support up to 20,000 features. Polygon overlay operations require area geometry; buffer point or line inputs first.
Result handles include a type, schema version, feature count, byte estimate, bounding box, dataset versions, operation hash, and lineage. They expire after 15 minutes, are scoped to the issuing key, and are cleared on service restart. Expired handles return HANDLE_EXPIRED; unknown or inaccessible handles return NOT_FOUND.
Each key can hold up to 64 handles and 192 MB of result data. HANDLE_QUOTA_EXCEEDED indicates that a handle allocation exceeds these limits. Download results for longer-term storage and use the returned metadata to track their source versions.
See plan limits for request allowances and error handling for quota and retry behavior.
Responses and examples
Area measurements use square meters; lengths and distances use meters. An intersection with no overlap returns null geometry. Pipeline responses include the selected result and execution metadata.
Example responses and timing measurements · Current service status
Attribution
Geometry derived from OpenStreetMap remains subject to ODbL. Keep © OpenStreetMap contributors with any derived result you publish.
Questions about this guide? Contact support.