Documentation
Build on the Data Foundation

Welcome to the Bantu Data API. This is your essential resource for integrating the market’s highest-quality, most comprehensive African Upstream data directly into your applications, models, and platforms. Follow the steps below to secure your API key and make your first successful call in minutes.

Getting Started

Get your API key and start accessing field data programmatically

Authentication

Include your API key in the X-API-Key header:

X-API-Key: ak_your_api_key_here

API Endpoints

List Field Data

Retrieve all field data submissions with pagination. Maximum page size varies by tier.

GET https://json-static-schema-form-mbuyambaf.replit.app/api/v1/field-data

Query parameters: page (default: 1), limit (default: 20)
Max page size by tier: Developer Sandbox (50), Professional (100), Enterprise Nexus (200), Custom Feed (500)

Get Single Field Data

Retrieve a specific field data submission by ID

GET https://json-static-schema-form-mbuyambaf.replit.app/api/v1/field-data/:id

Response Metadata

All API responses include a _meta object with tier-specific information:

tier - Your current pricing tier details
usage - Current billing period usage (data points used, remaining, request count)
usage.overage - Only present if you've exceeded your monthly limit (paid tiers only)
requestedAt - Timestamp of the request

Code Examples

Ready-to-use code snippets for multiple languages

List Field Data

curl -X GET "https://json-static-schema-form-mbuyambaf.replit.app/api/v1/field-data?page=1&limit=20" \  -H "X-API-Key: ak_your_api_key_here"

Response:

{
 "data": [
   {
     "id": "uuid",
     "fieldId": "NG-OML-118-BONGA",
     "data": {
       "metadata": {
         "name": "Bonga Field",
         "country": "Nigeria",
         "operator": "Shell Nigeria"
       },
       "location": { ... },
       "reserves_summary": { ... }
     },
     "completionPercentage": "85",
     "createdAt": "2024-11-22T10:30:00Z",
     "updatedAt": "2024-11-22T14:15:00Z"
   }
 ],
 "pagination": {
   "page": 1,
   "limit": 20,
   "total": 42,
   "totalPages": 3
 }
}

Get Single Field Data

curl -X GET "https://json-static-schema-form-mbuyambaf.replit.app/api/v1/field-data/uuid-here" \  -H "X-API-Key: ak_your_api_key_here"

Response:

{
 "id": "uuid",
 "fieldId": "NG-OML-118-BONGA",
 "data": {
   "metadata": {
     "name": "Bonga Field",
     "country": "Nigeria",
     "operator": "Shell Nigeria"
   },
   "location": { ... },
   "license_block": { ... },
   "technical_static": { ... },
   "reserves_summary": { ... }
 },
 "completionPercentage": "85",
 "createdAt": "2024-11-22T10:30:00Z",
 "updatedAt": "2024-11-22T14:15:00Z"}
}

Using requests library

import requests

API_KEY = "ak_your_api_key_here"
BASE_URL = "https://json-static-schema-form-mbuyambaf.replit.app/api/v1"

headers = {
   "X-API-Key": API_KEY
}

# List field data
response = requests.get(
   f"{BASE_URL}/field-data",
   headers=headers,
   params={"page": 1, "limit": 20}
)
data = response.json()
print(f"Found {data['pagination']['total']} records")

# Get specific field
response = requests.get(
   f"{BASE_URL}/field-data/uuid-here",
   headers=headers
)
field = response.json()
print(f"Field: {field['data']['metadata']['name']}")

Using fetch (Node.js or Browser)

const API_KEY = "ak_your_api_key_here";
const BASE_URL = "https://json-static-schema-form-mbuyambaf.replit.app/api/v1";

const headers = {
 "X-API-Key": API_KEY
};

// List field data
const listResponse = await fetch(
 `${BASE_URL}/field-data?page=1&limit=20`,
 { headers }
);
const { data, pagination } = await listResponse.json();
console.log(`Found ${pagination.total} records`);

// Get specific field
const fieldResponse = await fetch(
 `${BASE_URL}/field-data/uuid-here`,
 { headers });
const field = await fieldResponse.json();
console.log(`Field: ${field.data.metadata.name}`);

Using cURL

<?php
$apiKey = "ak_your_api_key_here";
$baseUrl = "https://json-static-schema-form-mbuyambaf.replit.app/api/v1";

$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
   "X-API-Key: $apiKey"
]);

// List field data
curl_setopt($ch, CURLOPT_URL, "$baseUrl/field-data?page=1&limit=20");
$response = curl_exec($ch);
$data = json_decode($response, true);
echo "Found " . $data['pagination']['total'] . " records\n";

// Get specific field
curl_setopt($ch, CURLOPT_URL, "$baseUrl/field-data/uuid-here");
$response = curl_exec($ch);
$field = json_decode($response, true);
echo "Field: " . $field['data']['metadata']['name'] . "\n";

curl_close($ch);
?>

Using net/http

require 'net/http'
require 'json'
require 'uri'

API_KEY = "ak_your_api_key_here"
BASE_URL = "https://json-static-schema-form-mbuyambaf.replit.app/api/v1"

# List field data
uri = URI("#{BASE_URL}/field-data?page=1&limit=20")
request = Net::HTTP::Get.new(uri)
request['X-API-Key'] = API_KEY

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
 http.request(request)
end

data = JSON.parse(response.body)
puts "Found #{data['pagination']['total']} records"

# Get specific field
uri = URI("#{BASE_URL}/field-data/uuid-here")
request = Net::HTTP::Get.new(uri)
request['X-API-Key'] = API_KEY

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
 http.request(request)
end

field = JSON.parse(response.body)
puts "Field: #{field['data']['metadata']['name']}"

Using HttpClient (Java 11+)

java.net.http.*;
import java.net.URI;
import org.json.JSONObject;

public class FieldDataAPI {
   private static final String API_KEY = "ak_your_api_key_here";
   private static final String BASE_URL = "https://json-static-schema-form-mbuyambaf.replit.app/api/v1";

   public static void main(String[] args) throws Exception {
       HttpClient client = HttpClient.newHttpClient();

       // List field data
       HttpRequest listRequest = HttpRequest.newBuilder()
           .uri(URI.create(BASE_URL + "/field-data?page=1&limit=20"))
           .header("X-API-Key", API_KEY)
           .GET()
           .build();

       HttpResponse<String> listResponse = client.send(
           listRequest,
           HttpResponse.BodyHandlers.ofString()
       );

       JSONObject data = new JSONObject(listResponse.body());
       System.out.println(
           "Found " +
           data.getJSONObject("pagination").getInt("total") +
           " records"
       );

       // Get specific field
       HttpRequest fieldRequest = HttpRequest.newBuilder()
           .uri(URI.create(BASE_URL + "/field-data/uuid-here"))
           .header("X-API-Key", API_KEY)
           .GET()
           .build();

       HttpResponse<String> fieldResponse = client.send(
           fieldRequest,
           HttpResponse.BodyHandlers.ofString()
       );

       JSONObject field = new JSONObject(fieldResponse.body());
       System.out.println(
           "Field: " +
           field.getJSONObject("data")
               .getJSONObject("metadata")
               .getString("name")
       );
   }
}

Error Handling

401 Unauthorized

Invalid or missing API key. Check the X-API-Key header.

404 Not Found

The requested field data submission does not exist.

429 Too Many Requests

Rate limit exceeded. Please slow down your requests.

Best Practices

✅ Store API keys securely in environment variables or secrets managers

✅ Use pagination to avoid large response payloads

✅ Implement error handling and retries in your code

✅ Cache responses when appropriate to reduce API calls

❌ Never commit API keys to version control

❌ Don't expose API keys in client-side code or URLs

Create your account today and get started for free!