API Documentation

TatetaGeo - Indonesian Regional Data Service

← Back to Home

Getting Started

TatetaGeo API provides access to comprehensive Indonesian regional data including provinces, regencies, districts, and villages. All endpoints require authentication using a Bearer token.

Base URL: https://your-domain.com/api/v1/geo

Quick Start

  1. Sign up and validate your email
  2. Get your API token from the dashboard
  3. Include the token in your requests as a Bearer token
  4. Start querying regional data

Authentication

All API requests require authentication using a Bearer token. After signing up and validating your email, you can find your API token in your dashboard.

Using Your API Token

Include your token in the Authorization header: 

Authorization: Bearer YOUR_API_TOKEN

Example Request

curl -X GET "https://your-domain.com/api/v1/geo/provinces" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Base URL & Versioning

All API endpoints are prefixed with the base URL and API version. The current version is v1.

Base URL: https://your-domain.com/api/v1/geo

Endpoints

TatetaGeo provides endpoints for querying provinces, regencies, districts, and villages. All endpoints require authentication.

Provinces

GET /provinces

List all provinces in Indonesia

GET /provinces/find

Find a specific province by ID or name

Regencies

GET /regencies

List all regencies in Indonesia

GET /regencies/find

Find a specific regency by ID or name

Districts

GET /districts

List all districts in Indonesia

GET /districts/find

Find a specific district by ID or name

Villages

GET /villages

List all villages in Indonesia

GET /villages/find

Find a specific village by ID or name

Request Parameters

Common query parameters supported across endpoints:

Parameter Type Description
id string Filter by specific ID
name string Search by name (partial match)
province_id string Filter by province (for regencies, districts, villages)
regency_id string Filter by regency (for districts, villages)
district_id string Filter by district (for villages)

Response Format

All successful responses return JSON with the following structure:

Success Response

{
  "success": true,
  "data": [
    {
      "id": "31",
      "name": "DKI JAKARTA"
    },
    {
      "id": "32",
      "name": "JAWA BARAT"
    }
  ]
}

Response Properties

success

Boolean indicating if the request was successful

data

Array of objects containing the requested regional data

Error Handling

When an error occurs, the API returns a JSON response with error details:

Error Response

{
  "success": false,
  "message": "Unauthenticated.",
  "error": {
    "code": 401,
    "type": "AuthenticationError"
  }
}

HTTP Status Codes

Code Description
200 Success - Request completed successfully
400 Bad Request - Invalid request parameters
401 Unauthorized - Missing or invalid API token
404 Not Found - Resource not found
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error occurred

Code Examples

Here are examples of how to use the TatetaGeo API in different programming languages:

cURL

curl -X GET "https://your-domain.com/api/v1/geo/provinces" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

PHP (Laravel HTTP Client)

<?php

use Illuminate\Support\Facades\Http;

$response = Http::withToken('YOUR_API_TOKEN')
    ->timeout(2)
    ->get('https://your-domain.com/api/v1/geo/provinces');

$data = $response->json();
print_r($data);

Python (Requests)

import requests

url = "https://your-domain.com/api/v1/geo/provinces"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Accept": "application/json"
}

response = requests.get(url, headers=headers)
data = response.json()
print(data)

JavaScript (Fetch API)

fetch('https://your-domain.com/api/v1/geo/provinces', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Node.js (Axios)

const axios = require('axios');

axios.get('https://your-domain.com/api/v1/geo/provinces', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json'
  }
})
.then(response => console.log(response.data))
.catch(error => console.error('Error:', error));

Go (net/http)

package main

import (
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    url := "https://your-domain.com/api/v1/geo/provinces"
    
    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_TOKEN")
    req.Header.Set("Accept", "application/json")
    
    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    
    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Ruby (net/http)

require 'net/http'
require 'json'

uri = URI('https://your-domain.com/api/v1/geo/provinces')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer YOUR_API_TOKEN'
req['Accept'] = 'application/json'

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

data = JSON.parse(res.body)
puts data