API Documentation

Programmatically manage your map data with our REST API

API Documentation

Use the REST API to programmatically manage your map data. All requests require authentication.

API Endpoint Placeholder - Map ID required
https://mapsemble.com/api/v1/map/{MAP_ID}/features

Authentication (OAuth 2)

All API requests require OAuth 2 authentication. First, obtain an access token using your client credentials, then include it in the Authorization header.

Step 1 Request Access Token

POST to the token endpoint with your client credentials:

POST https://mapsemble.com/token

Request body (YAML format):

grant_type: client_credentials_with_user
client_id: your_client_id
client_secret: your_client_secret

Example curl request:

curl -X POST "https://mapsemble.com/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials_with_user&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

Response:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJS..."
}
Step 2 Use Access Token in API Requests

Include the access token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Note: Generate your client_id and client_secret from your profile page. Tokens expire after 3600 seconds (1 hour).

CRUD Operations

GET Retrieve all features
curl -X GET "https://mapsemble.com/api/v1/map/{MAP_ID}/features" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Returns a GeoJSON FeatureCollection with all features. Supports pagination via query parameters.

Query parameters:

  • page — page number (default: 1)
  • per_page — features per page (default: 200, max: 500)

Paginated example:

curl -X GET "https://mapsemble.com/api/v1/map/{MAP_ID}/features?page=1&per_page=500" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

To retrieve all features, iterate pages until a page returns fewer than per_page features.

POST Create new features

Request body (YAML format):

features:
  - type: Feature
    geometry:
      type: Point
      coordinates:
        - -73.985428   # longitude
        - 40.748817    # latitude
    properties:
      title: My Location
      description: Description here

Example curl request (JSON):

curl -X POST "https://mapsemble.com/api/v1/map/{MAP_ID}/features" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -d '{ "features": [ { "type": "Feature", "geometry": { "type": "Point", "coordinates": [-73.985428, 40.748817] }, "properties": { "title": "My Location", "description": "Description here" } } ] }'

Create new features. Do not include an ID - it will be auto-generated. Maximum 1000 features per request.

PUT Full sync (upserts + removes unmatched)

Warning: PUT performs full reconciliation — it upserts all submitted features and deletes any existing features on the map that are not included in this request. Maximum 1000 features per request.

Use remoteField to match features by a property value (e.g. an external record ID) rather than internal UUID. The backend will upsert matching features and delete all others.

Example curl request (JSON) using remoteField:

curl -X PUT "https://mapsemble.com/api/v1/map/{MAP_ID}/features" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -d '{ "type": "FeatureCollection", "remoteField": "_airtable_id", "features": [ { "type": "Feature", "geometry": { "type": "Point", "coordinates": [-73.985428, 40.748817] }, "properties": { "_airtable_id": "recXXXXXXXXXXXXXX", "title": "My Location" } } ] }'

Use PATCH for partial updates to individual features without triggering reconciliation.

DELETE Delete features

Delete by internal ID:

curl -X DELETE "https://mapsemble.com/api/v1/map/{MAP_ID}/features" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -d '{ "features": [ { "id": "feature-uuid-to-delete" } ] }'

Delete by remoteField value (stub features with geometry: null):

curl -X DELETE "https://mapsemble.com/api/v1/map/{MAP_ID}/features" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -d '{ "type": "FeatureCollection", "remoteField": "_airtable_id", "features": [ { "type": "Feature", "geometry": null, "properties": { "_airtable_id": "recXXXXXXXXXXXXXX" } } ] }'

Use the remoteField pattern to delete features matched by an external identifier without knowing their internal UUIDs.

Response Format

Successful operations return a JSON response with success and/or failed arrays indicating the status of each feature operation.

{ "success": [ { "id": "uuid", "message": "Feature successfully created." } ], "failed": [ { "id": "uuid", "path": "field", "message": "Error message" } ] }

Important Notes

  • Maximum 1000 features per request
  • Coordinates should be in [longitude, latitude] format (GeoJSON standard)
  • All write operations (POST, PUT, PATCH, DELETE) require the owner's authentication
  • GET requests return a GeoJSON FeatureCollection; use ?page=N&per_page=500 to paginate large datasets — stop when a page returns fewer than per_page features
  • PUT performs full reconciliation — features not included in the request are deleted from the map (max 1000 features)

Conectémonos.

Programe una llamada de 30 minutos con nuestro equipo para discutir su proyecto.
O rellene el formulario y nos pondremos en contacto con usted lo antes posible.