Developer Utility APIs | Thousand API

Distance

Calculates distance between two points.

MCP tool: calculate_distance

GET /v1/distance

Parameters:

Parameter	Type	Required	Description
p1	string	✓	Point 1 lat,lon (e.g. 35.681236,139.767125)
p2	string	✓	Point 2 lat,lon (e.g. 34.702485,135.495951)

Request example:

curl "https://api.thousand-api.com/v1/distance?p1=35.681236,139.767125&p2=34.702485,135.495951" \
  -H "x-api-key: YOUR_API_KEY"

Response example:

{
  "p1": { "lat": 35.681236, "lon": 139.767125 },
  "p2": { "lat": 34.702485, "lon": 135.495951 },
  "distance_km": 402.3
}

Convert coordinates between WGS84 (GPS), Tokyo Datum (legacy Japanese geodetic system), JGD2011, and GSI/OSM/Google XYZ map tile coordinates. No external libraries; uses Molodensky approximation parameters.

MCP tool: convert_coordinates

WGS84 is the standard GPS coordinate system. Tokyo Datum (tokyo) was used on legacy GSI maps and government systems and can differ from WGS84 by up to about 450 m. JGD2011 (jgd2011) is practically identical to WGS84 but is accepted as a separate datum for future parameter updates. For tile conversion (to=tile), coordinates are normalized to WGS84 before Web Mercator XYZ tile calculation.

GET /v1/geo/convert

Parameters:

Parameter	Type	Required	Description
lat	number	✓	Latitude (-90 to 90)
lng	number	✓	Longitude (-180 to 180)
from	string	✓	Source datum: wgs84 / tokyo / jgd2011
to	string	✓	Target datum: wgs84 / tokyo / jgd2011 / tile
zoom	integer	-	Required when to=tile. Zoom level (integer 0–25)

Response fields:

When converting between datums (to is wgs84 / tokyo / jgd2011), output contains:

Parameter	Description
lat	Converted latitude (rounded to 8 decimal places)
lng	Converted longitude (rounded to 8 decimal places)

When to is tile, output contains:

Parameter	Description
zoom	Zoom level from the request
x	Tile X index (longitude axis, zero-based)
y	Tile Y index (latitude axis; smaller values are farther north)

Request example:

Example 1: WGS84 → Tokyo Datum (convert GPS to legacy Japanese datum)

curl "https://api.thousand-api.com/v1/geo/convert?lat=35.6812&lng=139.7671&from=wgs84&to=tokyo" \
  -H "x-api-key: YOUR_API_KEY"

{
  "from": "wgs84",
  "to": "tokyo",
  "input": { "lat": 35.6812, "lng": 139.7671 },
  "output": { "lat": 35.68109304, "lng": 139.76727453 }
}

Example 2: Tokyo Datum → WGS84 (legacy data to GPS coordinates)

curl "https://api.thousand-api.com/v1/geo/convert?lat=35.68109304&lng=139.76727453&from=tokyo&to=wgs84" \
  -H "x-api-key: YOUR_API_KEY"

{
  "from": "tokyo",
  "to": "wgs84",
  "input": { "lat": 35.68109304, "lng": 139.76727453 },
  "output": { "lat": 35.6812, "lng": 139.7671 }
}

Example 3: WGS84 → tile coordinates (zoom=15, GSI-style XYZ)

curl "https://api.thousand-api.com/v1/geo/convert?lat=35.6812&lng=139.7671&from=wgs84&to=tile&zoom=15" \
  -H "x-api-key: YOUR_API_KEY"

{
  "from": "wgs84",
  "to": "tile",
  "input": { "lat": 35.6812, "lng": 139.7671 },
  "output": { "zoom": 15, "x": 29105, "y": 12903 }
}

Color Palette

Generates color palettes (complementary, analogous, triadic, tetradic, shades) from a base hex color. No external dependencies; uses HSL color space for mathematically accurate results.

MCP tool: generate_color_palette

GET /v1/color/palette

Parameters:

Parameter	Type	Required	Description
color	string	✓	Base color in #RRGGBB format
type	string	-	complementary / analogous / triadic / tetradic / shades

Request example:

curl "https://api.thousand-api.com/v1/color/palette?color=%231976D2&type=complementary" \
  -H "x-api-key: YOUR_API_KEY"

Response example:

{
  "base": "#1976D2",
  "type": "complementary",
  "palette": [
    {
      "hex": "#1976D2",
      "rgb": "rgb(25, 118, 210)",
      "hsl": "hsl(211, 79%, 46%)",
      "name": "base"
    },
    {
      "hex": "#D27619",
      "rgb": "rgb(210, 118, 25)",
      "hsl": "hsl(31, 79%, 46%)",
      "name": "complement"
    }
  ]
}

WCAG Color Contrast

Calculates the WCAG 2.1 contrast ratio between a foreground and background color and returns AA/AAA compliance flags plus a recommendation string. No external dependencies; uses the official relative luminance algorithm.

MCP tool: calc_color_contrast

WCAG 2.1 thresholds: AA normal text 4.5:1, AA large text / UI 3:1, AAA normal text 7:1, AAA large text 4.5:1. Large text means 18pt+ or 14pt+ bold.

Pair palette hex values from generate_color_palette as foreground/background and call this API to filter down to accessible combinations in agent workflows.

GET /v1/color/contrast

Parameters:

Parameter	Type	Required	Description
foreground	string	✓	Foreground HEX (#RRGGBB, RRGGBB, or 3-digit shorthand)
background	string	✓	Background HEX (#RRGGBB, RRGGBB, or 3-digit shorthand)

Request example:

curl "https://api.thousand-api.com/v1/color/contrast?foreground=%23FFFFFF&background=%231976D2" \
  -H "x-api-key: YOUR_API_KEY"

Response example:

Example 1: Sufficient contrast (#FFFFFF / #1976D2)

{
  "foreground": "#FFFFFF",
  "background": "#1976D2",
  "contrast_ratio": 4.6,
  "wcag_aa_normal": true,
  "wcag_aa_large": true,
  "wcag_aaa_normal": false,
  "wcag_aaa_large": true,
  "recommendation": "AA normal + AAA large: good for most use cases (ratio: 4.6:1)"
}

Example 2: Insufficient contrast (Fail)

{
  "foreground": "#777777",
  "background": "#888888",
  "contrast_ratio": 1.26,
  "wcag_aa_normal": false,
  "wcag_aa_large": false,
  "wcag_aaa_normal": false,
  "wcag_aaa_large": false,
  "recommendation": "Fail: insufficient contrast for any WCAG level (ratio: 1.26:1)"
}

Response fields:

Parameter	Description
foreground	Normalized foreground color (uppercase #RRGGBB)
background	Normalized background color (uppercase #RRGGBB)
contrast_ratio	WCAG contrast ratio (2 decimal places)
wcag_aa_normal	Passes AA for normal text (>= 4.5:1)
wcag_aa_large	Passes AA for large text / UI (>= 3:1)
wcag_aaa_normal	Passes AAA for normal text (>= 7:1)
wcag_aaa_large	Passes AAA for large text (>= 4.5:1)
recommendation	Highest compliance level summary (English)

Math Expression Eval

Safely evaluate mathematical expressions. Supports arithmetic, trigonometry, statistics, unit conversion, and variable bindings. Does not use JavaScript eval — runs in a mathjs sandbox with dangerous functions (import, parse, etc.) disabled. A 100ms timeout blocks oversized computations.

MCP tool: calc_expression

POST /v1/math/eval

Parameters:

Parameter	Type	Required	Description
expression	string	required	Expression to evaluate (max 500 characters)
variables	object	-	Variable bindings (values must be number / string / boolean)
precision	integer	-	Decimal places for numeric results (0–15, omit for no limit)

Response fields:

Parameter	Description
expression	Echo of the input expression
variables	Variables used (null when omitted)
result	Evaluation result (number / string / boolean)
result_str	String form of result
precision	Precision applied (null when omitted)

Tax-inclusive calculation example:

Request example:

curl -X POST "https://api.thousand-api.com/v1/math/eval" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expression": "(100000 + 50000) * 1.1"
  }'

Response example:

{
  "expression": "(100000 + 50000) * 1.1",
  "variables": null,
  "result": 165000,
  "result_str": "165000",
  "precision": null
}

Compound interest with variable bindings:

Request example:

curl -X POST "https://api.thousand-api.com/v1/math/eval" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expression": "principal * (1 + rate)^years",
    "variables": {
      "principal": 1000000,
      "rate": 0.05,
      "years": 10
    },
    "precision": 0
  }'

Response example:

{
  "expression": "principal * (1 + rate)^years",
  "variables": {
    "principal": 1000000,
    "rate": 0.05,
    "years": 10
  },
  "result": 1628895,
  "result_str": "1628895",
  "precision": 0
}

Math function (Pythagorean theorem) example:

Request example:

curl -X POST "https://api.thousand-api.com/v1/math/eval" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expression": "sqrt(x^2 + y^2)",
    "variables": {
      "x": 3,
      "y": 4
    }
  }'

Response example:

{
  "expression": "sqrt(x^2 + y^2)",
  "variables": {
    "x": 3,
    "y": 4
  },
  "result": 5,
  "result_str": "5",
  "precision": null
}

Semver Version Compare

Compare, sort, and validate semantic version strings (semver). Correctly handles cases like 1.10.0 > 1.9.0 that string comparison gets wrong. Supports prerelease versions and range satisfaction checks (e.g. ^1.0.0, >=2.0.0-beta).

MCP tool: compare_versions

POST /v1/version/compare

Parameters:

Parameter	Type	Required	Description
versions	string[]	-	List of versions to sort and find latest from (max 100 items)
compare	string	-	Source version for comparison (must be paired with against)
against	string	-	Target version for comparison (must be paired with compare)
include_prerelease	boolean	-	Include prerelease versions in sorted/latest (default: false)
satisfies	object	-	Map of range pattern to version to check (key=range, value=version)

Response fields:

Parameter	Type	Description
compare	string	Request compare value (when specified)
against	string	Request against value (when specified)
result	number	Comparison result: 1=compare is newer / 0=equal / -1=compare is older (when specified)
result_label	string	Text form of result: greater / equal / less (when specified)
sorted	string[]	Versions sorted ascending (when versions specified)
latest_stable	string \| null	Newest stable version (when versions specified)
satisfies	object	Whether each range is satisfied (when satisfies specified)

Compare two versions:

Request example:

curl -X POST "https://api.thousand-api.com/v1/version/compare" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "compare": "1.10.0",
    "against": "1.9.0"
  }'

Response example:

{
  "compare": "1.10.0",
  "against": "1.9.0",
  "result": 1,
  "result_label": "greater"
}

Combined sort, compare, and range check:

Request example:

curl -X POST "https://api.thousand-api.com/v1/version/compare" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "versions": ["1.9.0", "1.10.0", "2.0.0-beta.1", "2.0.0"],
    "compare": "2.0.0",
    "against": "1.10.0",
    "include_prerelease": false,
    "satisfies": {
      "^1.9.0": "1.10.0",
      ">=2.0.0": "2.0.0-beta.1"
    }
  }'

Response example:

{
  "compare": "2.0.0",
  "against": "1.10.0",
  "result": 1,
  "result_label": "greater",
  "sorted": ["1.9.0", "1.10.0", "2.0.0"],
  "latest_stable": "2.0.0",
  "satisfies": {
    "^1.9.0": true,
    ">=2.0.0": false
  }
}

Developer utilities

Distance

GET /v1/distance

Coordinate conversion

GET /v1/geo/convert

Color Palette

GET /v1/color/palette

WCAG Color Contrast

GET /v1/color/contrast

Math Expression Eval

POST /v1/math/eval

Semver Version Compare

POST /v1/version/compare