openapi: 3.0.0
info:
  title: Api Reverse Geocoding API
  description: >-
    Complete API collection for reverse geocoding services. Features include reverse geocoding (coordinates to address),
    detailed address breakdown, OpenStreetMap integration, multiple address components (road, city, country, etc.),
    bounding box information, and place ranking with importance scores.
  version: 1.0.0
servers:
  - url: https://use.api.co.id
tags:
  - name: Api Reverse Geocoding
    description: Reverse geocoding endpoints to convert coordinates to addresses.
paths:
  /location/reverse-geocode:
    get:
      tags:
        - Api Reverse Geocoding
      summary: Reverse Geocode
      description: >-
        Convert coordinates (latitude, longitude) to a human-readable address.
        Returns detailed address breakdown with multiple components including road, city, country,
        postal code, and bounding box information.
      parameters:
        - name: x-api-co-id
          in: header
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
        - name: lat
          in: query
          required: true
          schema:
            type: number
            format: float
            minimum: -90
            maximum: 90
          description: Latitude coordinate (-90 to 90)
          example: -6.2088
        - name: lon
          in: query
          required: true
          schema:
            type: number
            format: float
            minimum: -180
            maximum: 180
          description: Longitude coordinate (-180 to 180)
          example: 106.8456
      responses:
        '200':
          description: Success - Address Retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  is_success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Success
                  data:
                    type: object
                    properties:
                      place_id:
                        type: integer
                        description: Place ID from OpenStreetMap
                        example: 123456789
                      licence:
                        type: string
                        description: License information
                        example: 'Data © OpenStreetMap contributors, ODbL 1.0'
                      lat:
                        type: number
                        format: float
                        description: Latitude
                        example: -6.2088
                      lon:
                        type: number
                        format: float
                        description: Longitude
                        example: 106.8456
                      display_name:
                        type: string
                        description: Full formatted address
                        example: 'Jl. Merdeka Selatan No. 11, Gambir, Jakarta Pusat, DKI Jakarta 10110, Indonesia'
                      address:
                        type: object
                        description: Address components
                        properties:
                          road:
                            type: string
                            description: Street name
                            example: 'Jl. Merdeka Selatan'
                          house_number:
                            type: string
                            description: House/building number
                            example: '11'
                          suburb:
                            type: string
                            description: Suburb/neighborhood
                            example: 'Gambir'
                          city:
                            type: string
                            description: City name
                            example: 'Jakarta Pusat'
                          state:
                            type: string
                            description: State/province
                            example: 'DKI Jakarta'
                          postcode:
                            type: string
                            description: Postal code
                            example: '10110'
                          country:
                            type: string
                            description: Country name
                            example: 'Indonesia'
                          country_code:
                            type: string
                            description: Two-letter country code
                            example: 'id'
                      boundingbox:
                        type: array
                        items:
                          type: string
                        description: Bounding box coordinates [min_lat, max_lat, min_lon, max_lon]
                        example:
                          - '-6.2091'
                          - '-6.2085'
                          - '106.8453'
                          - '106.8459'
                      importance:
                        type: number
                        format: float
                        description: Place importance score (0.0 to 1.0)
                        example: 0.85
              examples:
                success:
                  summary: Success - Address Retrieved
                  value:
                    is_success: true
                    message: Success
                    data:
                      place_id: 123456789
                      licence: 'Data © OpenStreetMap contributors, ODbL 1.0'
                      lat: -6.2088
                      lon: 106.8456
                      display_name: 'Jl. Merdeka Selatan No. 11, Gambir, Jakarta Pusat, DKI Jakarta 10110, Indonesia'
                      address:
                        road: 'Jl. Merdeka Selatan'
                        house_number: '11'
                        suburb: 'Gambir'
                        city: 'Jakarta Pusat'
                        state: 'DKI Jakarta'
                        postcode: '10110'
                        country: 'Indonesia'
                        country_code: 'id'
                      boundingbox:
                        - '-6.2091'
                        - '-6.2085'
                        - '106.8453'
                        - '106.8459'
                      importance: 0.85
                international:
                  summary: Success - International Location
                  value:
                    is_success: true
                    message: Success
                    data:
                      place_id: 987654321
                      licence: 'Data © OpenStreetMap contributors, ODbL 1.0'
                      lat: 37.7749
                      lon: -122.4194
                      display_name: 'Market Street, San Francisco, CA 94102, United States'
                      address:
                        road: 'Market Street'
                        city: 'San Francisco'
                        state: 'California'
                        postcode: '94102'
                        country: 'United States'
                        country_code: 'us'
                      boundingbox:
                        - '37.7745'
                        - '37.7753'
                        - '-122.4198'
                        - '-122.4190'
                      importance: 0.9
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Missing Coordinates:
                  summary: Missing Coordinates
                  value:
                    is_success: false
                    message: 'Both lat and lon parameters are required'
                Invalid Latitude:
                  summary: Invalid Latitude
                  value:
                    is_success: false
                    message: 'Latitude must be between -90 and 90. Got: invalid'
                Invalid Longitude:
                  summary: Invalid Longitude
                  value:
                    is_success: false
                    message: 'Longitude must be between -180 and 180'
                Invalid Coordinates:
                  summary: Invalid Coordinates Format
                  value:
                    is_success: false
                    message: 'Invalid coordinate format. Expected numeric values'
        '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:
                Location Not Found:
                  summary: Location Not Found
                  value:
                    is_success: false
                    message: 'No address found for the given coordinates'
        '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'
