{"openapi":"3.1.0","info":{"title":"OpenTripMap (BYOK) API","version":"0.1.0","description":"OpenTripMap (BYOK) lets an AI assistant read your own OpenTripMap data through the OpenTripMap API with a key you supply (OpenTripMap API key). Read-only: 5 tools (find_place_by_name, list_places_in_radius, list_places_in_bbox, get_place_details, suggest_places). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only ever sent to...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-opentripmap.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-opentripmap/docs"},"termsOfService":"https://connectorbay.com/byok-opentripmap/terms"},"servers":[{"url":"https://byok-opentripmap.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-opentripmap/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/find_place_by_name":{"post":{"operationId":"find_place_by_name","summary":"Turn a place name (city, village, region) into coordinates, country, time zone and population using GeoNames data. Use f","description":"Turn a place name (city, village, region) into coordinates, country, time zone and population using GeoNames data. Use for \"What are the coordinates of Lisbon in Portugal\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"lang":{"description":"Language of the answer: en or ru.","enum":["en","ru"],"title":"Lang","type":"string"},"name":{"description":"Place name to look up, for example 'Lisbon'.","maxLength":200,"title":"Name","type":"string"},"country":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter ISO 3166 country code to narrow the search, for example 'PT'.","title":"Country"}},"required":["lang","name"],"title":"find_place_by_nameArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_places_in_radius":{"post":{"operationId":"list_places_in_radius","summary":"List points of interest around a coordinate within a radius in metres, closest first, with category list and popularity ","description":"List points of interest around a coordinate within a radius in metres, closest first, with category list and popularity filter. Use for \"Which museums are within 2 km of the centre of Lisbon\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"lang":{"description":"Language of the answer: en or ru.","enum":["en","ru"],"title":"Lang","type":"string"},"radius":{"description":"Search radius in metres.","maximum":100000,"minimum":1,"title":"Radius","type":"number"},"lon":{"description":"Longitude of the centre point.","maximum":180,"minimum":-180,"title":"Lon","type":"number"},"lat":{"description":"Latitude of the centre point.","maximum":90,"minimum":-90,"title":"Lat","type":"number"},"kinds":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated OpenTripMap category names (OR logic), for example 'museums,historic'. Default is the interesting_places group.","title":"Kinds"},"rate":{"anyOf":[{"enum":["1","2","3","1h","2h","3h"],"type":"string"},{"type":"null"}],"default":null,"description":"Minimum popularity: 1, 2 or 3, add h for cultural heritage (1h, 2h, 3h). Default is every rating.","title":"Rate"},"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only places whose name starts with this text (at least 3 characters).","title":"Name"},"format":{"anyOf":[{"const":"json","type":"string"},{"type":"null"}],"default":"json","description":"Output format. Only json (a plain array) is supported here.","title":"Format"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum number of places to return (default 500 at the provider).","title":"Limit"}},"required":["lang","radius","lon","lat"],"title":"list_places_in_radiusArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_places_in_bbox":{"post":{"operationId":"list_places_in_bbox","summary":"List points of interest inside a bounding box given by minimum and maximum longitude and latitude. Use for \"What attract","description":"List points of interest inside a bounding box given by minimum and maximum longitude and latitude. Use for \"What attractions are in this map rectangle around Alfama in Lisbon\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"lang":{"description":"Language of the answer: en or ru.","enum":["en","ru"],"title":"Lang","type":"string"},"lon_min":{"description":"Western edge (minimum longitude).","maximum":180,"minimum":-180,"title":"Lon Min","type":"number"},"lon_max":{"description":"Eastern edge (maximum longitude).","maximum":180,"minimum":-180,"title":"Lon Max","type":"number"},"lat_min":{"description":"Southern edge (minimum latitude).","maximum":90,"minimum":-90,"title":"Lat Min","type":"number"},"lat_max":{"description":"Northern edge (maximum latitude).","maximum":90,"minimum":-90,"title":"Lat Max","type":"number"},"kinds":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated OpenTripMap category names (OR logic), for example 'museums,historic'. Default is the interesting_places group.","title":"Kinds"},"rate":{"anyOf":[{"enum":["1","2","3","1h","2h","3h"],"type":"string"},{"type":"null"}],"default":null,"description":"Minimum popularity: 1, 2 or 3, add h for cultural heritage (1h, 2h, 3h). Default is every rating.","title":"Rate"},"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only places whose name starts with this text (at least 3 characters).","title":"Name"},"format":{"anyOf":[{"const":"json","type":"string"},{"type":"null"}],"default":"json","description":"Output format. Only json (a plain array) is supported here.","title":"Format"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum number of places to return (default 500 at the provider).","title":"Limit"}},"required":["lang","lon_min","lon_max","lat_min","lat_max"],"title":"list_places_in_bboxArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_place_details":{"post":{"operationId":"get_place_details","summary":"Get one place by its OpenTripMap id (xid): name, categories, popularity rating, description, image, Wikipedia link and w","description":"Get one place by its OpenTripMap id (xid): name, categories, popularity rating, description, image, Wikipedia link and website. Use for \"Give me the details of the place with xid W286786280\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"lang":{"description":"Language of the answer: en or ru.","enum":["en","ru"],"title":"Lang","type":"string"},"xid":{"description":"OpenTripMap place id such as 'W286786280', taken from a place list.","maxLength":200,"title":"Xid","type":"string"}},"required":["lang","xid"],"title":"get_place_detailsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/suggest_places":{"post":{"operationId":"suggest_places","summary":"Autocomplete a place name near a coordinate: returns matching points of interest within a radius, with the matched text ","description":"Autocomplete a place name near a coordinate: returns matching points of interest within a radius, with the matched text highlighted. Use for \"Suggest places starting with 'cast' near Lisbon\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"lang":{"description":"Language of the answer: en or ru.","enum":["en","ru"],"title":"Lang","type":"string"},"name":{"description":"Search text, at least 3 characters.","maxLength":200,"title":"Name","type":"string"},"radius":{"description":"Search radius in metres around the point.","maximum":100000,"minimum":1,"title":"Radius","type":"number"},"lon":{"description":"Longitude of the centre point.","maximum":180,"minimum":-180,"title":"Lon","type":"number"},"lat":{"description":"Latitude of the centre point.","maximum":90,"minimum":-90,"title":"Lat","type":"number"},"kinds":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated OpenTripMap category names (OR logic), for example 'museums,historic'. Default is the interesting_places group.","title":"Kinds"},"rate":{"anyOf":[{"enum":["1","2","3","1h","2h","3h"],"type":"string"},{"type":"null"}],"default":null,"description":"Minimum popularity: 1, 2 or 3, add h for cultural heritage (1h, 2h, 3h). Default is every rating.","title":"Rate"},"format":{"anyOf":[{"const":"json","type":"string"},{"type":"null"}],"default":"json","description":"Output format. Only json (a plain array) is supported here.","title":"Format"},"props":{"anyOf":[{"enum":["base","address"],"type":"string"},{"type":"null"}],"default":"base","description":"Where to search: base (titles only, default) or address (titles and addresses).","title":"Props"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Maximum number of suggestions (default 10 at the provider).","title":"Limit"}},"required":["lang","name","radius","lon","lat"],"title":"suggest_placesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}