---
# System prepended metadata

title: carpark_hdb_sg.yaml
tags: [carpark_hdb_sg.yaml, Microservice Docs, yaml]

---

carpark_hdb_sg.yaml
===
###### tags: `Microservice Docs` `yaml` `carpark_hdb_sg.yaml`
---

openapi: 3.0.1
info:
  title: HDB Carpark Locations (SG)
  x-subscribelink: carpark_hdb_sg
  description: |+
    This Data microservice retrieves the Singapore Housing Development Board's carpark information within Singapore HDB estates that includes location address, postal code and parking lot capacity for different types of vehicle by carpark location. Updated monthly.
    The HDB POTH programme makes selected public and non-public datasets available to developers and companies to improve their service offerings to benefit the lives of Singapore citizens. Sentient.io is proud to partner with HDB to manage and facilitate the sharing of data for the POTH Programme.
    Suggested Use Cases: Geo-targeting app with map feature, property development planning resource, or planning for vehicle-sharing app.
    **Note:** As this microservice uses the GET method, developers using this microservice must remember to have their app encode all the input values to be URL friendly (i.e. all spaces and special characters must be replaced). Here’s a reference on [URL encoding](https://www.w3schools.com/tags/ref_urlencode.ASP).
  
  x-additionalinfo : |+
    **Refining queries in the filterdata field using filter types and match types**
    The filterdata fields use elasticsearch’s syntax (specifically filter types and match types) to help further refine search results and provide greater flexibility in structuring more sophisticated queries. 
  
    **Filter Types:**
    A filter type is a logic operator to which the search results must fulfill certain logical conditions to be returned. The supported match types are&#58;
    
    * **must** - All of the stated conditions must match. Equivalent to an AND operator.
      > {"must":[{"match":{"mc":0}}]}
    * **must_not** - All of the stated conditions must not match. Equivalent to a NOT operator.
      > {"must_not":[{"match":{"postalcode":"570251"}}]}
    
    * **should** - At least one of the stated conditions should match. Equivalent to an OR operator. 
      > {"should":[{"match_phrase":{"street":"ang mo kio"}}]}
    
    * **filter** - All of the stated conditions that must match. However, results are not scored unlike the other filter types which returns results based on how well the conditions are met.
      > {"filter":[{"match":{"street":"bishan"}}]}
      
    For a more detailed guide on filter types, [refer to this](https://www.elastic.co/guide/en/elasticsearch/reference/6.8/query-dsl-bool-query.html).
    
    Filter types cannot be used alone and must be used in conjunction with a match type to complete the query.
    **Match Types:**
    A match type is a match operator nested within a filter type that fine-tunes the matching condition of the text search. The supported match types are&#58;
    
    * **match** - Search within a full text field for a single word
      > {"match":{"street":"bishan"}}
    * **match_phrase** - Search within a full text field
      > {"match_phrase":{"street":"bishan street 24"}}
    * **match_phrase_prefix** - Search within a full text field with prefix
      > {"match_phrase_prefix":{"street":"bishan street 24"}}
    * **term** - Returns results that contain an exact term in a provided field
      > {"term":{"cpk_no":"ak19"}}
    * **terms** - Returns results that contain one or more exact terms in a provided field
      > {"terms":{"cpk_no":["ak19","be33"]}}
    * **range** - Returns results that contain terms within a stipulated range
      > {"range":{"car":{"gte":100}}}
      > {"range":{"car":{"lte":500}}}
      > {"range":{"car":{"gte":100,"lte":500}}}
    * **exists** - Returns results that contain any indexed value for a field
      > {"exists":{ "field": "postalcode"}}
    For a more detailed guide to match types, [refer to this](https://www.elastic.co/guide/en/elasticsearch/reference/7.9/term-level-queries.html).
    
    **Forming sophisticated queries using combinations of filter types (in JSON)**
    Multiple filter types can be combined together in one query (written in JSON format) to form a very sophisticated query. Here’s one example below&#58;
    
    > {
    > "must":[{"match":{"mc":0}}],
    > "filter":[{"match":{"street":"bishan"}}],
    > "should":[{"match_phrase":{"street":"ang mo kio"}}],
    > "must_not":[{"match":{"postalcode":"570251"}}]
    > }
    **Sample Queries Based on Use Cases**
    1. **Search for all carparks around 414 Bedok North Road**
       Using a querystring only&#58;
      
       > querystring = "414 bedok north road"
    2. **Search for all carparks within a 1KM radius from Tampines Mall**
       Using a filterdata only&#58;
       > filterdata = {"filter":[{"geo_distance": {"distance": "1km","location": "1.3525,103.9447"}}]}
      
    3. **Search for all carparks around Tampines with motorcycle parking**
       Using both querystring + filterdata&#58;
       
       > querystring = tampines
       > filterdata = {"filter":[ {"range":{"mc":{"gte":1}}} ]}
      
    4. **Search for all lorry parking lots for Bishan Street 22**
    
       Using both querystring + filterdata&#58;
      
       > querystring = "bishan street 22"
       > filterdata = {"filter":[ {"range":{"lorry":{"gte":1}}} ]}
  version: '0.1'
servers:
  - url: 'https://api.sentient.io'
tags:
- name: "v0.1"
  description: "Published Date - Oct 10, 2019"
paths:
   /DaaS/prod/hdb/carpark:
    get:
      tags:
        - v0.1
      parameters:
        - in: query
          name: querystring
          schema:
            type: string
          description: |+
            Simple keyword search for matches in all searchable fields. Keywords separated by spaces will return results containing any of those keywords. For exact phrase match, put entire phrase in double quotes (" ").
            
            If this field is set to null, by default the microservice will return all carparks (within the stated limit), which can be further refined through the filterdata field for more sophisticated queries.
            
          example: BE33
          default: false
        - in: query
          name: offset
          schema:
            type: integer
          description: The offset of the record list ie the starting index
          example: "0"
          default: false
        - in: query
          name: limit
          schema:
            type: integer
          description: The max records to return for the request. Default - 10, Max - 10000
          example: "10"
          default: false
        - in: query
          name: filterdata
          schema:
            type: string  
          description: |+
            Refine the search further on any of the possible through the 4 filter types &#58;
            * must
            * must_not
            * should
            * filter
          default: false
          example: |+
            {"must":[{"match":{"mc":0}}],"filter":[{"match":{"street":"bishan"}}],"should":[{"match_phrase":{"street":"ang mo kio"}}],"must_not":[{"match":{"postalcode":"570251"}}]}
      responses:
        '200':
          description: success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/success'
              example:
                results:
                  total: 1
                  max_score: 7.510164
                  hits:
                  - _index: sentient_carpark_hdb_index
                    _type: dir_doc
                    _id: BE37
                    _score: 7.510164
                    _source:
                      cpk_no: BE37
                      block: BLK 282
                      street: BISHAN STREET 22
                      address: BLK 282 BISHAN STREET 22
                      source: hdb
                      xcoord: '29235.553'
                      ycoord: '37787.1371'
                      car: 402
                      lorry: 40
                      mc: 0
                      createddate: '2020-09-11'
                      lastupdated: '2020-09-11'
                      location:
                        lat: 1.3580079412271227
                        lon: 103.84442083770412
                      postalcode:
                      - '570278'
                      - '570279'
                      - '570280'
                      - '570281'
                      - '570282'
                      - '570283'
                      - '570284'
                      - '570285'
                      - '570286'
                      - '570287'
                message: Successfully Processed
                status: Success
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paymentrequired'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/forbidden'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notfound'
        '419':
          description: Input Field Missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inputfieldmissing'
        '420':
          description: Input Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inputlimitexceeded'        
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/servererror'
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/gatewaytimeout'
      security:
        - APIAuthorizer: []
components:
  schemas:
    success:
      type: object
      properties:
        results:
          type: object
          example: {<Json Object>}
          description: Json Object of returned results
          properties:
            total:
              type: number
              example: 986
              description: Total number of records
            max_score:
              type: number
              example: 17.995623
              description: The highest score value
            hits:
              type: array
              example: [{<JSON result Object}]
              description: The list of Json result object
              items:
                type: object
                properties:
                  _index:
                    type: string
                    description: Index group of the document
                    example: "sentient_carpark_hdb_index"
                  _type: 
                    type: string
                    description: Content type of the document
                    example: "dir_doc"
                  _id: 
                    type: string
                    description: Document ID
                    example: "K7scqWgBv3dNEHq2WvMo"
                  _score: 
                    type: number
                    description: The document score for the search request
                    example: 17.995623
                  _source: 
                    type: object
                    example: {<Json Object>}
                    description: Json Object of returned hits
                    properties:
                            cpk_no: 
                              type: string
                              description: Carpark Number
                              example: AK19
                            block: 
                              type: string
                              description: Address block no
                              example: "BLOCK 253"
                            street: 
                              type: string
                              description: Address street or building name
                              example: "ANG MO KIO STREET 21"
                            address: 
                              type: string
                              description: Address full address
                              example: "BLOCK 253 ANG MO KIO STREET 21"
                            source: 
                              type: string
                              description: Dataset source
                              example: "hdb"
                            postalcode: 
                              type: array
                              description: List of postal code
                              example: ["570253", "570254"]
                              items:
                                type: string
                                description: postal code
                                example: "570253"
                            xcoord:
                              type: string
                              description: SVY21 X coordinates (Note, SVY21 is a localised plane coordinate system used specifically by Singapore. For global GPS lat/long coordinates, refer to "location" object)
                              example: 28185.4359
                            ycoord:
                              type: string
                              description: SVY21 Y coordinates (Note, SVY21 is a localised plane coordinate system used specifically by Singapore. For global GPS lat/long coordinates, refer to "location" object)
                              example: 39012.6664
                            location:
                              type: object
                              description: WGS84 (World Geodetic System) lat/long coordinates. This is the standard coordinate system used Global Positioning System (GPS).
                              example: {"lat":1.364299477060462,"lon":103.8350609414261}
                              properties:
                                  lat: 
                                    type: string
                                    description: WGS84 (GPS) latitude
                                    example: 1.37179535
                                  lon:
                                    type: string
                                    description: WGS84 (GPS) longitude
                                    example: 103.8469821
                            car:
                              type: number
                              description: Number of car parking lots
                              example: 18
                            lorry:
                              type: number
                              description: Number of lorry parking lots
                              example: 6
                            mc:
                              type: number
                              description: Number of motorcycle parking lots
                              example: 0
                            createddate:
                              type: string
                              description: Record first release date on sentient
                              example: "2019-10-17"
                            lastupdated:
                              type: string
                              description: Record last updated date on sentient
                              example: "2019-10-17"
        message:
          type: string
          example: Successfully Processed
          description: The detail description on the status
        status:
          type: string
          example: Success
          description: The status of the API call Success/Failure
    unauthorized:
      type: object
      properties:
        message:
          type: string
          example: Missing Authentication Token
        status:
          type: string
          example: Failure
    forbidden:
      type: object
      properties:
        message:
          type: string
          example: Access Denied Unauthorized User
        status:
          type: string
          example: Failure
    paymentrequired:
      type: object
      properties:
        message:
          type: string
          example: Insufficient Credits Kindly Top Up
        status:
          type: string
          example: Failure
    notfound:
      type: object
      properties:
        message:
          type: string
          example: Invalid Request URL
        status:
          type: string
          example: Failure
    servererror:
      type: object
      properties:
        message:
          type: string
          example: Internal Server Error
        status:
          type: string
          example: Failure
    gatewaytimeout:
      type: object
      properties:
        message:
          type: string
          example: Request Timeout
        status:
          type: string
          example: Failure
    inputfieldmissing:
      type: object
      properties:
        message:
          type: string
          example: Input Field Missing
        status:
          type: string
          example: Failure
    inputlimitexceeded:
      type: object
      properties:
        message:
          type: string
          example: Input Limit Exceeded
        status:
          type: string
          example: Failure
    versions:
      type: object
      properties: 
        v0.1:
         type: array
         items:
          oneOf:
            - type: string
              example: Published Date - Oct 10,2019
              description: Initial version release
  securitySchemes:
    APIAuthorizer:
      type: apiKey
      name: x-api-key
      in: header
      x-amazon-apigateway-authtype: custom
      description: Authentication is done using the x-api-key in the request header.