Early Adopter — 50% off. Ends May 31

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/maps/{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/maps/{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/maps/{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/maps/{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/maps/{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/maps/{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/maps/{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.