basePath: /
definitions:
  geocode-service_internal_model.PlaceResolveResponse:
    properties:
      result:
        $ref: '#/definitions/geocode-service_internal_model.ResolveResult'
    type: object
  geocode-service_internal_model.Prediction:
    properties:
      mainText:
        type: string
      placeId:
        type: string
      secondaryText:
        type: string
      text:
        type: string
      types:
        items:
          type: string
        type: array
    type: object
  geocode-service_internal_model.ResolveResult:
    properties:
      address:
        type: string
      city:
        type: string
      country:
        type: string
      district:
        type: string
      lat:
        type: number
      lon:
        type: number
      name:
        type: string
      placeId:
        type: string
      types:
        items:
          type: string
        type: array
    type: object
  geocode-service_internal_model.ReverseResponse:
    properties:
      results:
        items:
          $ref: '#/definitions/geocode-service_internal_model.ReverseResult'
        type: array
    type: object
  geocode-service_internal_model.ReverseResult:
    properties:
      address:
        type: string
      city:
        type: string
      confidence:
        type: number
      country:
        type: string
      distance_km:
        type: number
      district:
        type: string
      lat:
        type: number
      lon:
        type: number
      place_id:
        type: string
    type: object
  geocode-service_internal_model.SuggestResponse:
    properties:
      predictions:
        items:
          $ref: '#/definitions/geocode-service_internal_model.Prediction'
        type: array
    type: object
  internal_handler.batchGeocodeRequest:
    properties:
      addresses:
        items:
          type: string
        type: array
      country:
        type: string
      lang:
        type: string
    type: object
host: api.gogoduk.com
info:
  contact:
    email: support@gogoduk.com
    name: gogoduk support
    url: https://gogoduk.com
  description: |-
    Vietnam-focused geocoding, reverse geocoding, autocomplete, and POI search.
    Authenticate every /v1 request with the X-API-Key header.
  license:
    name: Proprietary
  termsOfService: https://gogoduk.com/terms
  title: gogoduk Geocoding API
  version: "1.0"
paths:
  /health:
    get:
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "503":
          description: Service Unavailable
          schema:
            additionalProperties: true
            type: object
      summary: Health check
      tags:
      - system
  /v1/admin-boundaries:
    get:
      description: Returns province/district polygons in GeoJSON or WKT.
      parameters:
      - default: geojson
        description: 'Output format: geojson or wkt'
        in: query
        name: format
        type: string
      - default: 4,8
        description: Comma-separated admin levels
        in: query
        name: levels
        type: string
      - default: VN
        description: ISO-3166-1 alpha-2
        in: query
        name: country_code
        type: string
      - description: Douglas-Peucker tolerance in degrees
        in: query
        name: tolerance
        type: number
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            additionalProperties: true
            type: object
      security:
      - ApiKeyAuth: []
      summary: Admin boundary polygons
      tags:
      - boundaries
  /v1/batch/geocode:
    post:
      consumes:
      - application/json
      description: |-
        Resolves up to 100 free-form addresses in one request. Results are
        returned in the same order as the input array. Each item resolves
        independently — an address that fails to match does not fail the
        batch; it returns null in `result` with an `error` field.
      parameters:
      - description: addresses (≤100)
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/internal_handler.batchGeocodeRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            additionalProperties: true
            type: object
      security:
      - ApiKeyAuth: []
      summary: Batch forward geocode
      tags:
      - geocoding
  /v1/categories:
    get:
      description: |-
        Returns the curated taxonomy of values accepted by
        /v1/pois?category=. Each row carries display labels in English
        and Vietnamese plus a Lucide icon hint for UIs.
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
      security:
      - ApiKeyAuth: []
      summary: List supported POI categories
      tags:
      - pois
  /v1/geocode:
    get:
      description: |-
        Resolves a free-form address string to a single best coordinate.
        Backed by the same fallback chain as /v1/suggest (ES → PG → Google),
        but returns one normalized result with a confidence score rather
        than a list of predictions.
      parameters:
      - description: Free-form address
        in: query
        name: address
        required: true
        type: string
      - default: VN
        description: ISO-3166-1 alpha-2 country bias
        in: query
        name: country
        type: string
      - default: vi
        description: Language code
        in: query
        name: lang
        type: string
      - description: Bias point latitude
        in: query
        name: focus.lat
        type: number
      - description: Bias point longitude
        in: query
        name: focus.lon
        type: number
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            additionalProperties: true
            type: object
        "404":
          description: Not Found
          schema:
            additionalProperties: true
            type: object
      security:
      - ApiKeyAuth: []
      summary: Forward geocode an address
      tags:
      - geocoding
  /v1/place/resolve:
    get:
      parameters:
      - description: Place identifier
        in: query
        name: id
        required: true
        type: string
      - default: vi
        description: Language code
        in: query
        name: lang
        type: string
      - description: Autocomplete session token (close billing session)
        in: query
        name: sessionToken
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/geocode-service_internal_model.PlaceResolveResponse'
        "400":
          description: Bad Request
          schema:
            additionalProperties: true
            type: object
        "503":
          description: Service Unavailable
          schema:
            additionalProperties: true
            type: object
      security:
      - ApiKeyAuth: []
      summary: Resolve a placeId into full place details
      tags:
      - geocoding
  /v1/pois:
    get:
      description: Returns a GeoJSON FeatureCollection of POIs ordered by distance
        to `near` (or bbox centre).
      parameters:
      - description: minLng,minLat,maxLng,maxLat
        in: query
        name: bbox
        required: true
        type: string
      - description: lng,lat — distance ranking centre
        in: query
        name: near
        type: string
      - default: 500
        description: Max results (1-2000)
        in: query
        name: limit
        type: integer
      - description: Comma-separated Google Places types (any-of)
        in: query
        name: category
        type: string
      - description: Filter by rating ≥ value
        in: query
        name: min_rating
        type: number
      - description: Only POIs marked open now
        in: query
        name: open_now
        type: boolean
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            additionalProperties: true
            type: object
      security:
      - ApiKeyAuth: []
      summary: Search POIs in a bounding box
      tags:
      - pois
  /v1/pois/{placeId}:
    get:
      description: Requires a valid X-POI-Token (issued in MVT tile responses).
      parameters:
      - description: Place identifier
        in: path
        name: placeId
        required: true
        type: string
      - description: Per-feature HMAC token
        in: header
        name: X-POI-Token
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            additionalProperties: true
            type: object
        "404":
          description: Not Found
          schema:
            additionalProperties: true
            type: object
      security:
      - ApiKeyAuth: []
      summary: Get a POI by placeId
      tags:
      - pois
  /v1/reverse:
    get:
      description: Returns the nearest known address(es) to point.lat/point.lon.
      parameters:
      - description: Latitude (WGS84)
        in: query
        name: point.lat
        required: true
        type: number
      - description: Longitude (WGS84)
        in: query
        name: point.lon
        required: true
        type: number
      - default: 1
        description: Max results (1-5)
        in: query
        name: size
        type: integer
      - default: 0.05
        description: Search radius in km, max 0.1
        in: query
        name: boundary.circle.radius
        type: number
      - default: vi
        description: Language code
        in: query
        name: lang
        type: string
      - description: Comma-separated ISO-3166-1 alpha-2 codes
        in: query
        name: boundary.country
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/geocode-service_internal_model.ReverseResponse'
        "400":
          description: Bad Request
          schema:
            additionalProperties: true
            type: object
        "503":
          description: Service Unavailable
          schema:
            additionalProperties: true
            type: object
      security:
      - ApiKeyAuth: []
      summary: Reverse geocode a coordinate
      tags:
      - geocoding
  /v1/reverse-geocode:
    get:
      description: Returns the province/district that contains the given lat/lng (PostGIS
        ST_Contains).
      parameters:
      - description: Latitude
        in: query
        name: lat
        required: true
        type: number
      - description: Longitude
        in: query
        name: lng
        required: true
        type: number
      - default: 4,8
        description: Comma-separated admin levels
        in: query
        name: levels
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            additionalProperties: true
            type: object
      security:
      - ApiKeyAuth: []
      summary: Admin-boundary reverse geocode
      tags:
      - geocoding
  /v1/suggest:
    get:
      description: Returns predictions for a partial address. Input must be ≥ 2 characters.
      parameters:
      - description: User input (min 2 chars)
        in: query
        name: input
        required: true
        type: string
      - default: vi
        description: Language code
        in: query
        name: lang
        type: string
      - description: ISO-3166-1 country filter (alpha-2 or alpha-3)
        in: query
        name: country
        type: string
      - description: Autocomplete session token
        in: query
        name: sessionToken
        type: string
      - description: Bias point latitude
        in: query
        name: focus.lat
        type: number
      - description: Bias point longitude
        in: query
        name: focus.lon
        type: number
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/geocode-service_internal_model.SuggestResponse'
        "400":
          description: Bad Request
          schema:
            additionalProperties: true
            type: object
      security:
      - ApiKeyAuth: []
      summary: Autocomplete address suggestions
      tags:
      - geocoding
  /v1/usage:
    get:
      description: |-
        Returns request counts attributed to the authenticated key's
        owning user, plus today's quota state. Quota is summed across
        ALL of this user's API keys (regardless of org). Use it to
        pre-empt 429s in your client. Defaults to the last 30 days;
        pass `from` and `to` (YYYY-MM-DD) to override.
      parameters:
      - description: Start date (YYYY-MM-DD)
        in: query
        name: from
        type: string
      - description: End date (YYYY-MM-DD, inclusive)
        in: query
        name: to
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            additionalProperties: true
            type: object
        "400":
          description: Bad Request
          schema:
            additionalProperties: true
            type: object
        "503":
          description: Service Unavailable
          schema:
            additionalProperties: true
            type: object
      security:
      - ApiKeyAuth: []
      summary: Get this user's API usage and quota
      tags:
      - usage
schemes:
- https
- http
securityDefinitions:
  ApiKeyAuth:
    in: header
    name: X-API-Key
    type: apiKey
swagger: "2.0"