{"openapi":"3.1.0","info":{"title":"PearlGraph API","version":"0.7.0","description":"Open, source-backed Uganda tourism data with a source document for every record.","contact":{"name":"Oree Studios Africa","url":"https://pearlgraph.com/support","email":"support@pearlgraph.com"},"license":{"name":"Apache-2.0"},"termsOfService":"https://pearlgraph.com/terms"},"servers":[{"url":"https://pearlgraph.com/api/public/v1"}],"paths":{"/":{"get":{"tags":["Tourism"],"operationId":"getUgandaDataset","summary":"Uganda map and national travel requirements","description":"One base read returns travelRules (visa and essentials), map (GeoJSON FeatureCollection with connections), fees, seasons and operators. Every attraction contains applicable access rules, quotas, opening hours and fee references. Lodges and districts have null GeoJSON geometry and labelled routing anchors, not exact facility coordinates or administrative boundaries. Road connections include kilometres, drive minutes and endpoint coordinates, not surveyed polylines. Optional from and to together add a calculated journey. Sources and original validity dates are preserved.","parameters":[{"name":"from","in":"query","schema":{"type":"string","maxLength":100}},{"name":"to","in":"query","schema":{"type":"string","maxLength":100}},{"name":"audience","in":"query","schema":{"type":"string","enum":["foreign","local"]}},{"name":"month","in":"query","schema":{"type":"integer","minimum":1,"maximum":12}}],"responses":{"200":{"description":"Source-backed dataset with source catalogue","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"description":"Invalid filters"},"404":{"description":"Unknown road place or no route"}}},"post":{"summary":"Build or check an itinerary at the base address","description":"Provide exactly one of stops or days. stops builds a plan and may insert travel days; feasible means all requested activities fit the generated plan, not that they fit one day. days checks the supplied day allocation without extending it. Responses include schemaVersion, sources and data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["start"],"oneOf":[{"required":["stops"]},{"required":["days"]}],"properties":{"start":{"type":"string","minLength":1,"maxLength":60},"month":{"type":"integer","minimum":1,"maximum":12},"stops":{"type":"array","minItems":1,"maxItems":30,"items":{"$ref":"#/components/schemas/Stop"}},"days":{"type":"array","minItems":1,"maxItems":30,"items":{"type":"array","maxItems":6,"items":{"$ref":"#/components/schemas/Stop"}}}}},"example":{"start":"kampala","month":7,"stops":[{"attractionId":"kibale","activityId":"chimp-trek"}]}}}},"responses":{"200":{"description":"Generated plan or itinerary check"},"400":{"description":"Invalid body"},"422":{"description":"Unknown start id or unable to plan"}},"operationId":"planItineraryAtBase","tags":["Planning"]}},"/places":{"get":{"operationId":"getPlaces","tags":["Tourism"],"summary":"Attractions, districts and accommodation","description":"Returns data.attractions, data.districts and data.accommodation. q searches names; region filters attractions and districts; near, tier, district and type filter accommodation; category filters attractions. district also filters district names.","parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":100}},{"name":"region","in":"query","schema":{"type":"string","maxLength":100}},{"name":"category","in":"query","schema":{"type":"string","maxLength":100}},{"name":"near","in":"query","schema":{"type":"string","maxLength":100}},{"name":"tier","in":"query","schema":{"type":"string","maxLength":100}},{"name":"district","in":"query","schema":{"type":"string","maxLength":100}},{"name":"type","in":"query","schema":{"type":"string","maxLength":100}}],"responses":{"200":{"description":"Source-backed places grouped by record type"},"400":{"description":"Invalid filters"}}}},"/access":{"get":{"operationId":"getAccess","tags":["Tourism"],"summary":"Entry fees, permit quotas and park rules","description":"Returns data.fees, data.quotas and data.rules. ids filters comma-separated fee ids; attraction filters quotas by attraction id.","parameters":[{"name":"ids","in":"query","schema":{"type":"string","maxLength":100}},{"name":"attraction","in":"query","schema":{"type":"string","maxLength":100}}],"responses":{"200":{"description":"Tariffs, permit capacity and access rules"},"400":{"description":"Invalid filters"}}}},"/transport":{"get":{"operationId":"getTransport","tags":["Tourism"],"summary":"Road, air and water connections","description":"Returns data.road, data.airstrips, data.flights and data.ferries. Supply both from and to place ids for a road journey. Without from, to can search air connections alone. q filters ferries. Road drive time is adjusted for month.","parameters":[{"name":"from","in":"query","schema":{"type":"string","maxLength":100}},{"name":"to","in":"query","schema":{"type":"string","maxLength":100}},{"name":"q","in":"query","schema":{"type":"string","maxLength":100}},{"name":"month","in":"query","schema":{"type":"integer","minimum":1,"maximum":12}}],"responses":{"200":{"description":"Road distances, drive times, airstrips, flights and ferries"},"400":{"description":"Invalid filters"},"404":{"description":"Unknown road place or no route"}}}},"/guide":{"get":{"operationId":"getGuide","tags":["Tourism"],"summary":"Visitor essentials, seasons and operators","description":"Returns data.essentials, data.seasons and data.operators. audience filters essentials; region filters operators.","parameters":[{"name":"audience","in":"query","schema":{"type":"string","enum":["foreign","local"]}},{"name":"region","in":"query","schema":{"type":"string","maxLength":100}}],"responses":{"200":{"description":"Visa, entry, health and visitor guidance with source dates"},"400":{"description":"Invalid filters"}}}},"/plan":{"post":{"summary":"Plan (stops) or check (days) an itinerary","description":"Provide exactly one of stops or days. stops builds a plan and may insert travel days; feasible means all requested activities fit the generated plan, not that they fit one day. days checks the supplied day allocation without extending it. Responses include schemaVersion, sources and data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["start"],"oneOf":[{"required":["stops"]},{"required":["days"]}],"properties":{"start":{"type":"string","minLength":1,"maxLength":60},"month":{"type":"integer","minimum":1,"maximum":12},"stops":{"type":"array","minItems":1,"maxItems":30,"items":{"$ref":"#/components/schemas/Stop"}},"days":{"type":"array","minItems":1,"maxItems":30,"items":{"type":"array","maxItems":6,"items":{"$ref":"#/components/schemas/Stop"}}}}},"example":{"start":"kampala","month":7,"stops":[{"attractionId":"kibale","activityId":"chimp-trek"}]}}}},"responses":{"200":{"description":"Generated plan or itinerary check"},"400":{"description":"Invalid body"},"422":{"description":"Unknown start id or unable to plan"}},"operationId":"planItinerary","tags":["Planning"]}},"/attractions":{"get":{"summary":"Search attractions","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"region","in":"query","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Attractions"}},"operationId":"getAttractions","deprecated":true,"tags":["Legacy"]}},"/search":{"get":{"summary":"Meaning-based search across attractions, districts and stays","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ranked results with similarity score"},"400":{"description":"Missing q"}},"operationId":"getSearch","deprecated":true,"tags":["Legacy"]}},"/graph":{"get":{"summary":"Knowledge-graph links around a node (no node = stats)","parameters":[{"name":"node","in":"query","schema":{"type":"string"}},{"name":"depth","in":"query","schema":{"type":"string"}},{"name":"predicate","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Nodes and subject-predicate-object triples"},"404":{"description":"Unknown node"}},"operationId":"getGraph","deprecated":true,"tags":["Legacy"]}},"/fees":{"get":{"summary":"UWA tariffs, including low season permit rates","parameters":[{"name":"ids","in":"query","schema":{"type":"string"},"description":"Comma-separated fee ids"}],"responses":{"200":{"description":"Fees"}},"operationId":"getFees","deprecated":true,"tags":["Legacy"]}},"/route":{"get":{"summary":"Road route & drive time","parameters":[{"name":"from","in":"query","required":true,"schema":{"type":"string"},"example":"kampala"},{"name":"to","in":"query","required":true,"schema":{"type":"string"},"example":"bwindi-buhoma"},{"name":"month","in":"query","schema":{"type":"integer","minimum":1,"maximum":12}}],"responses":{"200":{"description":"Route"},"400":{"description":"Missing place ids or invalid month"},"404":{"description":"Unknown place"}},"operationId":"getRoute","deprecated":true,"tags":["Legacy"]}},"/permits":{"get":{"summary":"Permit quotas per sector and access rules","parameters":[{"name":"attraction","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Quotas and rules"}},"operationId":"getPermits","deprecated":true,"tags":["Legacy"]}},"/flights":{"get":{"summary":"Airstrips and domestic flights","parameters":[{"name":"to","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Airstrips and flights"}},"operationId":"getFlights","deprecated":true,"tags":["Legacy"]}},"/ferries":{"get":{"summary":"Lake and river ferries","parameters":[{"name":"q","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Ferries"}},"operationId":"getFerries","deprecated":true,"tags":["Legacy"]}},"/seasons":{"get":{"summary":"Dry & wet seasons","responses":{"200":{"description":"Seasons"}},"operationId":"getSeasons","deprecated":true,"tags":["Legacy"]}},"/operators":{"get":{"summary":"Institutions & operators","parameters":[{"name":"region","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Operators"}},"operationId":"getOperators","deprecated":true,"tags":["Legacy"]}},"/districts":{"get":{"summary":"All districts with tourism highlights","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"region","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Districts"}},"operationId":"getDistricts","deprecated":true,"tags":["Legacy"]}},"/lodges":{"get":{"summary":"Lodges near attractions (no prices)","parameters":[{"name":"near","in":"query","schema":{"type":"string"}},{"name":"tier","in":"query","schema":{"type":"string"}},{"name":"district","in":"query","schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Lodges"}},"operationId":"getLodges","deprecated":true,"tags":["Legacy"]}},"/essentials":{"get":{"summary":"Visa categories, entry rules, health, customs and global planning checklist","parameters":[{"name":"audience","in":"query","schema":{"type":"string","enum":["foreign","local"]}}],"responses":{"200":{"description":"Essentials with source dates and structured visa rules. Recommendations are distinguished from entry requirements."}},"operationId":"getEssentials","deprecated":true,"tags":["Legacy"]}}},"components":{"schemas":{"Stop":{"type":"object","required":["attractionId","activityId"],"properties":{"attractionId":{"type":"string"},"activityId":{"type":"string"}}},"Source":{"type":"object","required":["id","url","published"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"published":{"type":["string","null"],"format":"date"},"accessed":{"type":"string","format":"date"}}},"BaseResponse":{"type":"object","required":["schemaVersion","sources","travelRules","map","fees"],"properties":{"schemaVersion":{"type":"string"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"travelRules":{"type":"object","properties":{"visa":{"type":"object"},"essentials":{"type":"array","items":{"type":"object"}}}},"map":{"type":"object","properties":{"type":{"type":"string","enum":["FeatureCollection"]},"features":{"type":"array","items":{"type":"object","required":["id","geometry","properties"],"properties":{"id":{"type":"string"},"geometry":{"type":["object","null"]},"properties":{"type":"object"}}}},"connections":{"type":"object"},"counts":{"type":"object"}}},"fees":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"validFrom":{"type":"string","format":"date"},"validTo":{"type":"string","format":"date"},"validityStatus":{"type":"string","enum":["expired","not-yet-valid","within-published-period"]}}}}}}}},"jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","tags":[{"name":"Tourism"},{"name":"Planning"},{"name":"Legacy","description":"Existing addresses remain supported. Use the grouped endpoints for new connections."}]}