API Reference

Tools

Utility endpoints that support the main API workflows. Currently includes geocoding for GEO-type field searches.

GET /v1/geocode

Convert an address or place name to latitude/longitude coordinates. Use the returned coordinates as meta.{key}_lat and meta.{key}_lng parameters when searching listings with GEO-type fields.

Query Parameters

Parameter	Type	Required	Description
`q`	string	✅	Address or place name (e.g. "San Francisco, CA", "Seoul")

Request

curl "https://api.markidy.com/v1/geocode?q=San%20Francisco" \
  -H "Authorization: Bearer mk_your_api_key"

Response

{
  "query": "San Francisco",
  "results": [
    {
      "name": "San Francisco",
      "address": "San Francisco, CA, USA",
      "lat": 37.7749295,
      "lng": -122.4194155
    }
  ]
}

Response Fields

Field	Type	Description
`query`	string	Original search query
`results`	array	Geocoding results (may be empty if no match found)
`results[].name`	string	Place name
`results[].address`	string	Formatted address
`results[].lat`	number	Latitude
`results[].lng`	number	Longitude

Usage with Search

After obtaining coordinates, use them in the listings search endpoint:

GEO Search Flow

# Step 1: Geocode the address
curl "https://api.markidy.com/v1/geocode?q=Seoul" \
  -H "Authorization: Bearer mk_your_api_key"
# → { "results": [{ "lat": 37.5665, "lng": 126.978 }] }

# Step 2: Use coordinates in search
curl "https://api.markidy.com/v1/listings/search?category=education&meta.location_lat=37.5665&meta.location_lng=126.978" \
  -H "Authorization: Bearer mk_your_api_key"
# → results sorted by distance, each with "distanceKm" field

When _lat and _lng parameters are provided, search results are automatically sorted by proximity (nearest first) and each result includes a distanceKm field.

Errors

Status	Code	Description
400	`VALIDATION_ERROR`	`q` parameter is missing or empty
500	`GEOCODE_ERROR`	Geocoding service error (upstream failure)

Previous ← Conversations Next Webhooks →