API Reference

Programmatic access to your places, trips, and profile.

#Base URL

https://api.globe.cv/v1

#Authentication

All requests require an API key as a Bearer token in the Authorization header.

Open Settings > API to generate a key. Copy it immediately. It won't be shown again.

curl https://api.globe.cv/v1/places \
  -H "Authorization: Bearer gcv_your_key_here"

#Rate Limiting

Requests are rate limited per API key. When limited, the API returns 429 with a Retry-After header.

Tier	Limit
Free	10 requests/min
Premium	60 requests/min
Public (no auth)	30 requests/min by IP

#Response Format

JSON with a success boolean. Errors include an error string.

{ "success": true, "places": [...] }

{ "success": false, "error": "Invalid API key" }

#Places

#GET /places

List your places.

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	50	Results per page (max 100)
category	string	-	Filter by category
search	string	-	Search by name
sort	string	date_added	Sort field
order	string	desc	asc or desc
format	string	json	json or geojson

curl "https://api.globe.cv/v1/places?limit=10&category=city" \
  -H "Authorization: Bearer gcv_your_key_here"

Response:

{
  "success": true,
  "places": [
    {
      "id": "550e8400-...",
      "name": "Tokyo",
      "category": "city",
      "latitude": 35.6762,
      "longitude": 139.6503,
      "identifier": "tokyo-japan"
    }
  ],
  "pagination": { "page": 1, "limit": 10, "total": 42, "pages": 5 }
}

#POST /places

Create a place. Send an array for batch creation (max 10).

Parameter	Type	Default	Description
name	string	required	Place name
latitude	number	required	Latitude (-90 to 90)
longitude	number	required	Longitude (-180 to 180)
category	string	-	Place category
identifier	string	-	Unique slug
skip_enrichment	boolean	false	Skip AI enrichment

curl -X POST https://api.globe.cv/v1/places \
  -H "Authorization: Bearer gcv_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Tokyo", "latitude": 35.6762, "longitude": 139.6503}'

Response:

{ "success": true, "place": { "id": "550e8400-...", "name": "Tokyo", ... } }

#GET /places/:id

Get a single place by ID.

curl https://api.globe.cv/v1/places/PLACE_ID \
  -H "Authorization: Bearer gcv_your_key_here"

#PATCH /places/:id

Update a place. All fields optional.

curl -X PATCH https://api.globe.cv/v1/places/PLACE_ID \
  -H "Authorization: Bearer gcv_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Tokyo Tower"}'

#DELETE /places/:id

Delete a place.

curl -X DELETE https://api.globe.cv/v1/places/PLACE_ID \
  -H "Authorization: Bearer gcv_your_key_here"

#Profile

#GET /me

Get your profile.

curl https://api.globe.cv/v1/me \
  -H "Authorization: Bearer gcv_your_key_here"

Response:

{
  "success": true,
  "profile": {
    "username": "marcopolo",
    "display_name": "Marco Polo",
    "bio": "Traveler",
    "avatar_url": null
  }
}

#PATCH /me

Update your display name or bio.

curl -X PATCH https://api.globe.cv/v1/me \
  -H "Authorization: Bearer gcv_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"display_name": "New Name"}'

#Trips

#GET /trips

List your trips.

curl https://api.globe.cv/v1/trips \
  -H "Authorization: Bearer gcv_your_key_here"

Response:

{
  "success": true,
  "trips": [{ "id": "550e8400-...", "title": "Japan 2025", "visibility": "public" }]
}

#POST /trips

Create a trip.

Parameter	Type	Default	Description
title	string	required	Trip title
latitude	number	required	Center latitude
longitude	number	required	Center longitude
visibility	string	private	public or private

curl -X POST https://api.globe.cv/v1/trips \
  -H "Authorization: Bearer gcv_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"title": "Japan 2025", "latitude": 35.68, "longitude": 139.69}'

#GET /trips/:id

Get a trip and its segments.

curl https://api.globe.cv/v1/trips/TRIP_ID \
  -H "Authorization: Bearer gcv_your_key_here"

#PATCH /trips/:id

Update title or visibility.

curl -X PATCH https://api.globe.cv/v1/trips/TRIP_ID \
  -H "Authorization: Bearer gcv_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated Title"}'

#DELETE /trips/:id

Delete a trip and all its segments.

curl -X DELETE https://api.globe.cv/v1/trips/TRIP_ID \
  -H "Authorization: Bearer gcv_your_key_here"

#Trip Segments

#GET /trips/:id/segments

List segments for a trip.

curl https://api.globe.cv/v1/trips/TRIP_ID/segments \
  -H "Authorization: Bearer gcv_your_key_here"

#POST /trips/:id/segments

Add a segment.

Parameter	Type	Default	Description
order_index	integer	required	Position in trip
transport_type	string	required	flight, train, car, bus, boat, walk, bike, other
title	string	-	Segment title
start_date	string	-	ISO 8601 date
end_date	string	-	ISO 8601 date

curl -X POST https://api.globe.cv/v1/trips/TRIP_ID/segments \
  -H "Authorization: Bearer gcv_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"order_index": 0, "transport_type": "flight", "title": "Tokyo to Osaka"}'

#PATCH /trips/:id/segments/:segmentId

Update a segment.

curl -X PATCH https://api.globe.cv/v1/trips/TRIP_ID/segments/SEGMENT_ID \
  -H "Authorization: Bearer gcv_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated Segment"}'

#DELETE /trips/:id/segments/:segmentId

Delete a segment.

curl -X DELETE https://api.globe.cv/v1/trips/TRIP_ID/segments/SEGMENT_ID \
  -H "Authorization: Bearer gcv_your_key_here"

#Public Data

No authentication required. Rate limited to 30/min by IP.

#GET /users/:username

Public profile.

curl https://api.globe.cv/v1/users/marcopolo

#GET /users/:username/places

Public places. Pass format=geojson for GeoJSON.

curl https://api.globe.cv/v1/users/marcopolo/places?format=geojson

#GET /users/:username/trips

Public trips. Pass includeSegments=true for full data.

curl https://api.globe.cv/v1/users/marcopolo/trips?includeSegments=true

#GET /featured-places

List featured place categories.

curl https://api.globe.cv/v1/featured-places

#GET /featured-places/:group

Featured places by category.

curl https://api.globe.cv/v1/featured-places/city

#Error Codes

Status	Description
400	Bad request: missing or invalid parameters
401	Unauthorized: missing or invalid API key
403	Forbidden: place limit reached for your plan
404	Not found
405	Method not allowed
429	Rate limited
500	Server error

Questions? support@globe.cv