Polygon Centroid Calculator API: The Complete Guide

Need to find the center point of a polygon or geographic region? This guide covers everything about centroid calculation via API, including different centroid types, formulas, and implementation examples.

What is a Centroid?

A centroid is the geometric center of a shape - the point where the shape would balance perfectly if made of a uniform material. For polygons, it's calculated from the vertices and represents the "center of mass."

In geographic contexts, the centroid is useful for labeling regions, placing markers, or finding representative locations for areas.

Types of Centroids

Geometric Centroid

The true center of mass based on the polygon's area. This is the most commonly used type and handles concave polygons correctly.

Bounding Box Center

The center of the polygon's bounding box. Faster to calculate but less accurate for irregularly shaped polygons.

Point-on-Surface

A point guaranteed to be inside the polygon. Useful when the geometric centroid falls outside (for concave shapes).

Using the Centroid API

TinyFn provides a simple endpoint to calculate polygon centroids:

POST https://api.tinyfn.io/v1/geo/centroid
Headers: X-API-Key: your-api-key
Content-Type: application/json

{
  "polygon": [
    {"lat": 40.7484, "lng": -73.9967},
    {"lat": 40.7484, "lng": -73.9717},
    {"lat": 40.7680, "lng": -73.9717},
    {"lat": 40.7680, "lng": -73.9967}
  ]
}

{
  "centroid": {
    "lat": 40.7582,
    "lng": -73.9842
  },
  "type": "geometric",
  "inside_polygon": true,
  "area_sq_km": 0.456
}

Parameters

Code Examples

JavaScript / Node.js

const response = await fetch(
  'https://api.tinyfn.io/v1/geo/centroid',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      polygon: [
        { lat: 40.7484, lng: -73.9967 },
        { lat: 40.7484, lng: -73.9717 },
        { lat: 40.7680, lng: -73.9717 },
        { lat: 40.7680, lng: -73.9967 }
      ]
    })
  }
);
const { centroid } = await response.json();
console.log(`Center: ${centroid.lat}, ${centroid.lng}`);

Python

import requests

response = requests.post(
    'https://api.tinyfn.io/v1/geo/centroid',
    headers={'X-API-Key': 'your-api-key'},
    json={
        'polygon': [
            {'lat': 40.7484, 'lng': -73.9967},
            {'lat': 40.7484, 'lng': -73.9717},
            {'lat': 40.7680, 'lng': -73.9717},
            {'lat': 40.7680, 'lng': -73.9967}
        ]
    }
)
centroid = response.json()['centroid']
print(f"Center: {centroid['lat']}, {centroid['lng']}")

cURL

curl -X POST "https://api.tinyfn.io/v1/geo/centroid" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "polygon": [
      {"lat": 40.7484, "lng": -73.9967},
      {"lat": 40.7484, "lng": -73.9717},
      {"lat": 40.7680, "lng": -73.9717},
      {"lat": 40.7680, "lng": -73.9967}
    ]
  }'

Common Use Cases

• Map Labeling: Place labels at the center of geographic regions
• Marker Placement: Position markers representing polygon features
• Distance Calculations: Use centroid as representative point for distance to regions
• Clustering: Use centroids as cluster representatives
• Analytics: Aggregate data to centroids for visualization

Best Practices

1. Check containment: Verify the centroid is inside the polygon when needed
2. Use point-on-surface: For concave polygons where inside point is required
3. Close the polygon: Ensure first and last vertices match
4. Handle multi-polygons: Calculate weighted centroid for regions with multiple parts

Use via MCP

Your AI agent can call this tool directly via Model Context Protocol — no HTTP code needed. Add TinyFn to Claude Desktop, Cursor, or any MCP client:

{
  "mcpServers": {
    "tinyfn-geo": {
      "url": "https://api.tinyfn.io/mcp/geo/",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

See all geolocation tools available via MCP in our Geolocation MCP Tools for AI Agents guide.