Proxi External API Documentation

##**API Endpoints**###**1. Create Single Point****Endpoint:** `POST /topics/{topic_id}/point?api_key={api_key}`

Creates a single point on the specified map topic.

###**Request Body**```json
{
  "category": "restaurant",
  "name": "Amazing Pizza Place",
  "description": "Best pizza in town with authentic Italian recipes",

  // Location Option 1: Coordinates
  "latitude": 40.7128,
  "longitude": -74.0060,

  // Location Option 2: Address (alternative to coordinates)
  "address": "123 Main Street, New York, NY 10001",

  // Optional fields
  "special_offer": "10% off for new customers",
  "active": true,
  "featured": false,
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-12-31T23:59:59Z",
  "number": "+1-555-123-4567",
  "url": "<https://amazingpizza.com>",
  "default_hidden": false,
  "tag_info": ["italian", "pizza", "delivery"],
  "image_urls_to_add": [
    "<https://example.com/pizza1.jpg>",
    "<https://example.com/pizza2.jpg>"
  ],
  "custom_fields": [
    {
      "field_name": "Price Range",
      "value": "$$"
    },
    {
      "field_name": "Delivery Available",
      "value": "Yes"
    }
  ]
}

###Location Input Options

You must provideexactly one of the following location methods:

1.Coordinates (most precise): json { "latitude": 40.7128, "longitude": -74.0060 } 2. Address (geocoded automatically): json { "address": "Times Square, New York, NY" }

###Required Fields- category: Must match an existing category in your topic -Location: One of the location methods above

###Response****Success (201 Created):```json { "_id": "507f1f77bcf86cd799439011", "write_key": "abc123def456", "read_key": "xyz789uvw012" }


**Error (400 Bad Request):**```json
{
  "error": "VALIDATION_ERROR",
  "message": "Latitude must be between -90 and 90 degrees",
  "error_code": "INVALID_LATITUDE",
  "field_errors": {
    "latitude": ["Latitude must be between -90 and 90 degrees"]
  }
}

###**2. Create Multiple Points (Bulk)**Endpoint: POST /topics/{topic_id}/points?api_key={api_key}

Creates multiple points in a single request for improved efficiency.

###Request Body```json [ { "category": "restaurant", "name": "Pizza Place 1", "latitude": 40.7128, "longitude": -74.0060 }, { "category": "restaurant", "name": "Pizza Place 2", "address": "456 Broadway, New York, NY" }, { "category": "cafe", "name": "Coffee Shop", "place_id": "ChIJmQJIxlVYwokRLgeuocVOGVU" } ]


###**Response****Success (201 Created):**```json
{
  "updated_point_ids": [
    "507f1f77bcf86cd799439011",
    "507f1f77bcf86cd799439012",
    "507f1f77bcf86cd799439013"
  ],
  "failed_validations": [],
  "failed_geocodes": [],
  "metadata": {
    "total_processed": 3,
    "geocoding_used": true,
    "rate_limit_remaining": 57,
    "rate_limit_reset_seconds": 45
  }
}

Partial Success (201 Created):```json { "updated_point_ids": [ "507f1f77bcf86cd799439011" ], "failed_validations": [ { "request": { "category": "invalid_category", "name": "Failed Point" }, "errors": { "category": ["Category 'invalid_category' does not exist in this topic"] } } ], "failed_geocodes": [ { "category": "restaurant", "name": "Ungeocodable Location", "address": "Invalid Address That Cannot Be Found" } ], "metadata": { "total_processed": 3, "geocoding_used": true, "rate_limit_remaining": 57, "rate_limit_reset_seconds": 45 } }


---

###**3. Update Single Point****Endpoint:** `PUT /topics/{topic_id}/point?api_key={api_key}&point_id={point_id}`

Updates a single point on the specified map topic.

- Only include fields you want to update in the request body.
- The same field structure and rules as the POST endpoint apply.

####**Request Body Example**```json
{
  "name": "Amazing Pizza Place - Updated",
  "description": "Updated description for the pizza place",
  "latitude": 40.7130,
  "longitude": -74.0055,
  "active": false
}

####Response****Success (200 OK):```json { "updated_point_id": "507f1f77bcf86cd799439011", "message": "Point updated successfully" }


**Error (400 Bad Request):**```json
{
  "error": "VALIDATION_ERROR",
  "message": "Invalid update parameters",
  "error_code": "INVALID_FIELD",
  "field_errors": {
    "latitude": ["Latitude must be between -90 and 90 degrees"]
  }
}

###**4. Update Multiple Points (Bulk)**Endpoint: PUT /topics/{topic_id}/points?api_key={api_key}

Bulk update multiple points in a single request.

Each object in the array must include the point_id of the point to update.
Only include fields you want to update for each point.

####Request Body Example```json [ { "point_id": "507f1f77bcf86cd799439011", "name": "Pizza Place 1 - Updated", "active": false }, { "point_id": "507f1f77bcf86cd799439012", "name": "Pizza Place 2 - Updated", "category": "diner", "address": "789 Avenue, New York, NY" } ]


####**Response****Success (200 OK):**```json
{
  "updated_point_ids": [
    "507f1f77bcf86cd799439011",
    "507f1f77bcf86cd799439012"
  ],
  "failed_updates": [],
  "metadata": {
    "total_processed": 2,
    "rate_limit_remaining": 58,
    "rate_limit_reset_seconds": 35
  }
}

Partial Success (200 OK):```json { "updated_point_ids": [ "507f1f77bcf86cd799439011" ], "failed_updates": [ { "point_id": "507f1f77bcf86cd799439012", "errors": { "category": ["Category 'diner' does not exist in this topic"] } } ], "metadata": { "total_processed": 2, "rate_limit_remaining": 58, "rate_limit_reset_seconds": 35 } }


---

###**5. Delete Point****Endpoint:** `DELETE /topics/{topic_id}/point?api_key={api_key}&point_id={point_id}`

Deletes a single point from the specified topic.

####**Parameters**- `topic_id`: The ID of the topic containing the point
- `point_id`: The ID of the point to delete
- `api_key`: Your organization's API key

####**Response****Success (204 No Content):** Empty response body

**Error (400 Bad Request):**```json
{
  "error": "VALIDATION_ERROR",
  "message": "The point does not belong to the topic",
  "error_code": "POINT_TOPIC_MISMATCH"
}


## **Overview**

The Proxi External API v1 provides programmatic access to create, manage, and delete points on your maps. This RESTful API is designed for developers who want to integrate Proxi into their applications, automate data entry, or build custom workflows. This is just a start, and we are open to hearing about what other APIs you are interested in having available. 

## **Getting Started**

### **API Authentication**

To use the External API, you'll need an API key associated with your organization.

**🔑 Request API Access:** Contact [**[email protected]**](<mailto:[email protected]>) with your organization details to receive your API key. Soon we plan to publish a way to access this yourself. 

### **Base URL**

All API requests should be made to:

`https://map.proxi.co/api/v1`

### OpenAPI Documentation

[`https://map.proxi.co/v1_docs`](<https://map.proxi.co/v1_docs>)

[<https://map.proxi.co/v1_docs/index.html>](<https://map.proxi.co/v1_docs/index.html>)

### **Authentication Method**

Include your API key as a query parameter in every request:

`?api_key=YOUR_API_KEY_HERE`

### **Rate Limiting**

- **Rate Limit:** 60 requests per minute per topic
- **Headers:** API responses include rate limiting information in the metadata