🔗 Base Endpoint
All requests are made to the GraphQL endpoint below:
https://geofactual-api.onrender.com/No authentication is required for public read-only queries.
To introspect the API, Open in Apollo Explorer(Clicking this button will open it in Apollo Explorer.)
Schema Overview
The full type Query definition is shown below:
type Query {
feature(name: String!): GeoFeature
waterBody(name: String!): WaterBody
# Paginated queries
waterBodies(kind: WaterType, salty: Boolean, start: Int = 0, first: Int = 10): [WaterBody!]!
landform(name: String!): LandformFeature
landforms(kind: Landform, start: Int = 0, first: Int = 10): [LandformFeature!]!
terrestrialBiome(name: String!): TerrestrialBiome
terrestrialBiomes(kind: TerrestrialBiomeType, continent: String, start: Int = 0, first: Int = 10): [TerrestrialBiome!]!
}
Query.landforms→ returns landform dataQuery.terrestrialBiomes→ returns data from terrestrial biomesQuery.waterBodies→ returns lakes, rivers, and oceans
Example Query
Here’s a sample GraphQL query to fetch all landforms:
query Landforms {
landforms(kind:PLATEAU) {
id
name
kind
altitudeInMeters
locations {
continent
country
latitude
longitude
}
}
}
Example response:
{
"data": {
"landforms": [
{
"id": "1",
"name": "Tibetan Plateau",
"kind": "PLATEAU",
"altitudeInMeters": 4500,
"locations": [
{
"continent": "Asia",
"country": "China",
"latitude": 32,
"longitude": 88
},
{
"continent": "Asia",
"country": "India",
"latitude": 34,
"longitude": 78
},
{
"continent": "Asia",
"country": "Nepal",
"latitude": 29,
"longitude": 85
}
]
},
{
"id": "2",
"name": "Bohemian Plateau",
"kind": "PLATEAU",
"altitudeInMeters": 500,
"locations": [
{
"continent": "Europe",
"country": "Czech Republic",
"latitude": 49.75,
"longitude": 14.5
}
]
},
{
"id": "3",
"name": "Jos Plateau",
"kind": "PLATEAU",
"altitudeInMeters": 1280,
"locations": [
{
"continent": "Africa",
"country": "Nigeria",
"latitude": 9.8,
"longitude": 8.9
}
]
}
]
}
}
Pagination Type Requests
There are certain times we might want to control the number of records to return per page. For instance 5 waterbody records:
query{
waterBodies(start:0, first:5){
id
name
kind
salty
areas {
name
avgDepthRangeInMeters
}
finalDestinations {
mouth
country
}
}
}
Where first is amount of records to return, start
is index to begin from.
Sending a feature Query
The feature query is for the union GeoFeature = WaterBody | LandformFeature | TerrestrialBiome. This
query can return any of the possible types.
query {
feature(name: "Nile") {
__typename
... on WaterBody {
id
name
waterKind: kind
salty
areas {
name
avgDepthRangeInMeters
}
finalDestinations {
mouth
country
}
sources {
name
locations {
country
continent
}
}
}
... on LandformFeature {
id
name
landformKind: kind
altitudeInMeters
locations {
continent
country
}
}
... on TerrestrialBiome {
id
name
terrestrialKind: kind
locations {
continent
country
}
}
}
}
Aliases(waterkind, landformKind, terrestrialKind) were added to kind for each feature field to
prevent errors.
The argument "Nile" was passed to the query.
Example response:
{
"data": {
"feature": {
"__typename": "WaterBody",
"id": "5",
"name": "Nile",
"waterKind": "RIVER",
"salty": false,
"areas": null,
"finalDestinations": [
{
"mouth": "Mediterranean sea",
"country": "Egypt"
}
],
"sources": [
{
"name": "White Nile",
"locations": [
{
"country": "Burundi",
"continent": "Africa"
},
{
"country": "Uganda",
"continent": "Africa"
},
{
"country": "South Sudan",
"continent": "Africa"
},
{
"country": "Sudan",
"continent": "Africa"
}
]
},
{
"name": "Blue Nile",
"locations": [
{
"country": "Ethiopia",
"continent": "Africa"
},
{
"country": "Sudan",
"continent": "Africa"
}
]
}
]
}
}
}
You can notice the response and then the __typename field value is "WaterBody". If
"Tibetian Plateau" was passed, the __typename will be "LandformFeature".
🔐 Mutations Only by Admin
The API is read-only for public users. Mutations are disabled for the public.
🌐 CORS & HTTPS
CORS is fully enabled. You can call the API directly from any frontend application.
All connections must use HTTPS.
📘 License & Contact
This API is maintained by Stephen Odogwu
For any issues email: stevepurpose@protonmail.com