openapi: 3.0.0
info:
  title: IP Geolocation API
  description: >-
    Complete API collection for IP geolocation services. Features include IP geolocation lookup,
    detailed location information (country, city, coordinates), country metadata (calling code, TLD, languages),
    currency information, continent and region details, and state/province information.
  version: 1.0.0
servers:
  - url: https://use.api.co.id
tags:
  - name: IP Geolocation
    description: IP geolocation endpoints to get location information from IP addresses.
paths:
  /location/ip-geolocation:
    get:
      tags:
        - IP Geolocation
      summary: Get IP Geolocation
      description: >-
        Get detailed geolocation information for an IP address including country, city, coordinates,
        country metadata, currency information, continent and region details.
      parameters:
        - name: x-api-co-id
          in: header
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
        - name: ip
          in: query
          required: true
          schema:
            type: string
            format: ipv4
          description: IP address to geolocate (IPv4 format)
          example: '103.123.45.67'
      responses:
        '200':
          description: Success - IP Geolocation Retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  is_success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Success
                  data:
                    type: object
                    properties:
                      ip:
                        type: string
                        description: IP address
                        example: '103.123.45.67'
                      country:
                        type: string
                        description: Country name
                        example: 'Indonesia'
                      country_code:
                        type: string
                        description: Two-letter country code (ISO 3166-1 alpha-2)
                        example: 'ID'
                      city:
                        type: string
                        description: City name
                        example: 'Jakarta'
                      region:
                        type: string
                        description: Region/state name
                        example: 'Jakarta'
                      latitude:
                        type: number
                        format: float
                        description: Latitude coordinate
                        example: -6.2088
                      longitude:
                        type: number
                        format: float
                        description: Longitude coordinate
                        example: 106.8456
                      timezone:
                        type: string
                        description: Timezone
                        example: 'Asia/Jakarta'
                      currency:
                        type: string
                        description: Currency code
                        example: 'IDR'
                      currency_name:
                        type: string
                        description: Currency name
                        example: 'Indonesian Rupiah'
                      calling_code:
                        type: string
                        description: Country calling code
                        example: '+62'
                      tld:
                        type: string
                        description: Top-level domain
                        example: '.id'
                      languages:
                        type: array
                        items:
                          type: string
                        description: List of languages spoken
                        example:
                          - 'Indonesian'
                          - 'English'
                      continent:
                        type: string
                        description: Continent name
                        example: 'Asia'
                      continent_code:
                        type: string
                        description: Two-letter continent code
                        example: 'AS'
                      isp:
                        type: string
                        description: Internet Service Provider
                        example: 'PT Telekomunikasi Indonesia'
                      organization:
                        type: string
                        description: Organization name
                        example: 'PT Telekomunikasi Indonesia'
              examples:
                success:
                  summary: Success - IP Geolocation
                  value:
                    is_success: true
                    message: Success
                    data:
                      ip: '103.123.45.67'
                      country: 'Indonesia'
                      country_code: 'ID'
                      city: 'Jakarta'
                      region: 'Jakarta'
                      latitude: -6.2088
                      longitude: 106.8456
                      timezone: 'Asia/Jakarta'
                      currency: 'IDR'
                      currency_name: 'Indonesian Rupiah'
                      calling_code: '+62'
                      tld: '.id'
                      languages:
                        - 'Indonesian'
                        - 'English'
                      continent: 'Asia'
                      continent_code: 'AS'
                      isp: 'PT Telekomunikasi Indonesia'
                      organization: 'PT Telekomunikasi Indonesia'
                international:
                  summary: Success - International IP
                  value:
                    is_success: true
                    message: Success
                    data:
                      ip: '8.8.8.8'
                      country: 'United States'
                      country_code: 'US'
                      city: 'Mountain View'
                      region: 'California'
                      latitude: 37.4056
                      longitude: -122.0775
                      timezone: 'America/Los_Angeles'
                      currency: 'USD'
                      currency_name: 'US Dollar'
                      calling_code: '+1'
                      tld: '.us'
                      languages:
                        - 'English'
                      continent: 'North America'
                      continent_code: 'NA'
                      isp: 'Google LLC'
                      organization: 'Google LLC'
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Missing IP:
                  summary: Missing IP Parameter
                  value:
                    is_success: false
                    message: 'IP parameter is required'
                Invalid IP Format:
                  summary: Invalid IP Format
                  value:
                    is_success: false
                    message: 'Invalid IP address format. Please provide a valid IPv4 address'
                Invalid IP Address:
                  summary: Invalid IP Address
                  value:
                    is_success: false
                    message: 'Invalid IP address: invalid.ip.address'
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Missing API Key:
                  summary: Missing API Key
                  value:
                    is_success: false
                    message: 'Missing API key in x-api-co-id header'
                Invalid API Key:
                  summary: Invalid API Key
                  value:
                    is_success: false
                    message: 'Invalid API key'
        '404':
          description: Not Found
          content:
            application/json:
              examples:
                IP Not Found:
                  summary: IP Not Found
                  value:
                    is_success: false
                    message: 'IP address not found in database'
        '429':
          description: Too Many Requests
          content:
            application/json:
              examples:
                Rate Limit Exceeded:
                  summary: Rate Limit Exceeded
                  value:
                    is_success: false
                    message: 'Rate limit exceeded. Please try again later'
