openapi: 3.0.3
info:
  title: 'API Documentation for BANOC API'
  description: 'This is the API endpoint and description for all terminaison in the banoc API'
  version: 1.0.0
servers:
  -
    url: 'https://dev.api.banoc.coeurduweb.com'
paths:
  /api/geocode/coordinates:
    get:
      summary: 'Coordinates Geocoding'
      operationId: coordinatesGeocoding
      description: 'This method make a reverse geocode, so take longitude and latitude from query string and return the geocode available with the level'
      parameters:
        -
          in: query
          name: latitude
          description: 'The latitude for the geocode.'
          example: 4.015296
          required: true
          schema:
            type: number
            description: 'The latitude for the geocode.'
            example: 4.015296
        -
          in: query
          name: longitude
          description: 'The longitude for the geocode.'
          example: 11.557123
          required: true
          schema:
            type: number
            description: 'The longitude for the geocode.'
            example: 11.557123
        -
          in: query
          name: level
          description: "The level of the polygon to retrieve. Here are the correspondances of level values :\n\n<table border=\"1\" style=\"border-collapse: collapse; border: 1px solid black;\">\n  <thead style=\"background-color: #D3D3D3;\">\n    <tr>\n      <th style=\"border: 1px solid black; padding: 5px;\">l (level code)</th>\n      <th style=\"border: 1px solid black; padding: 5px;\">Side length (technical)</th>\n      <th style=\"border: 1px solid black; padding: 5px;\">Side length (rounded, displayed on the application)</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td style=\"border: 1px solid black; padding: 5px;\">180</td>\n      <td style=\"border: 1px solid black; padding: 5px;\">1 m</td>\n      <td style=\"border: 1px solid black; padding: 5px;\">1 m</td>\n    </tr>\n    <tr>\n      <td style=\"border: 1px solid black; padding: 5px;\">155</td>\n      <td style=\"border: 1px solid black; padding: 5px;\">5,6 m</td>\n      <td style=\"border: 1px solid black; padding: 5px;\">5 m</td>\n    </tr>\n    <tr>\n      <td style=\"border: 1px solid black; padding: 5px;\">130</td>\n      <td style=\"border: 1px solid black; padding: 5px;\">32 m</td>\n      <td style=\"border: 1px solid black; padding: 5px;\">30 m</td>\n    </tr>\n    <tr>\n      <td style=\"border: 1px solid black; padding: 5px;\">105</td>\n      <td style=\"border: 1px solid black; padding: 5px;\">181 m</td>\n      <td style=\"border: 1px solid black; padding: 5px;\">200 m</td>\n    </tr>\n    <tr>\n      <td style=\"border: 1px solid black; padding: 5px;\">80</td>\n      <td style=\"border: 1px solid black; padding: 5px;\">1024 m</td>\n      <td style=\"border: 1px solid black; padding: 5px;\">1 km</td>\n    </tr>\n  </tbody>\n</table>"
          example: 155
          required: false
          schema:
            type: integer
            description: "The level of the polygon to retrieve. Here are the correspondances of level values :\n\n<table border=\"1\" style=\"border-collapse: collapse; border: 1px solid black;\">\n  <thead style=\"background-color: #D3D3D3;\">\n    <tr>\n      <th style=\"border: 1px solid black; padding: 5px;\">l (level code)</th>\n      <th style=\"border: 1px solid black; padding: 5px;\">Side length (technical)</th>\n      <th style=\"border: 1px solid black; padding: 5px;\">Side length (rounded, displayed on the application)</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td style=\"border: 1px solid black; padding: 5px;\">180</td>\n      <td style=\"border: 1px solid black; padding: 5px;\">1 m</td>\n      <td style=\"border: 1px solid black; padding: 5px;\">1 m</td>\n    </tr>\n    <tr>\n      <td style=\"border: 1px solid black; padding: 5px;\">155</td>\n      <td style=\"border: 1px solid black; padding: 5px;\">5,6 m</td>\n      <td style=\"border: 1px solid black; padding: 5px;\">5 m</td>\n    </tr>\n    <tr>\n      <td style=\"border: 1px solid black; padding: 5px;\">130</td>\n      <td style=\"border: 1px solid black; padding: 5px;\">32 m</td>\n      <td style=\"border: 1px solid black; padding: 5px;\">30 m</td>\n    </tr>\n    <tr>\n      <td style=\"border: 1px solid black; padding: 5px;\">105</td>\n      <td style=\"border: 1px solid black; padding: 5px;\">181 m</td>\n      <td style=\"border: 1px solid black; padding: 5px;\">200 m</td>\n    </tr>\n    <tr>\n      <td style=\"border: 1px solid black; padding: 5px;\">80</td>\n      <td style=\"border: 1px solid black; padding: 5px;\">1024 m</td>\n      <td style=\"border: 1px solid black; padding: 5px;\">1 km</td>\n    </tr>\n  </tbody>\n</table>"
            example: 155
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      gid: 1683577603
                      jurisd_local_id: 20904
                      l: 130
                      code_b32nvu: FQS3
                      geom: 0103000020787F000001000000050000000000000070EC274100000000581D1B4100000000B0EC274100000000581D1B4100000000B0EC274100000000D81D1B410000000070EC274100000000D81D1B410000000070EC274100000000581D1B41
                      centroide:
                        type: Point
                        coordinates:
                          lat: 11.557123313
                          lon: 4.015295585
                      polygon:
                        type: Polygon
                        coordinates:
                          -
                            -
                              lat: 11.556978868
                              lon: 4.015151433
                            -
                              lat: 11.557266857
                              lon: 4.015150528
                            -
                              lat: 11.557267758
                              lon: 4.015439738
                            -
                              lat: 11.556979768
                              lon: 4.015440642
                            -
                              lat: 11.556978868
                              lon: 4.015151433
                properties:
                  data:
                    type: array
                    example:
                      -
                        gid: 1683577603
                        jurisd_local_id: 20904
                        l: 130
                        code_b32nvu: FQS3
                        geom: 0103000020787F000001000000050000000000000070EC274100000000581D1B4100000000B0EC274100000000581D1B4100000000B0EC274100000000D81D1B410000000070EC274100000000D81D1B410000000070EC274100000000581D1B41
                        centroide:
                          type: Point
                          coordinates:
                            lat: 11.557123313
                            lon: 4.015295585
                        polygon:
                          type: Polygon
                          coordinates:
                            -
                              -
                                lat: 11.556978868
                                lon: 4.015151433
                              -
                                lat: 11.557266857
                                lon: 4.015150528
                              -
                                lat: 11.557267758
                                lon: 4.015439738
                              -
                                lat: 11.556979768
                                lon: 4.015440642
                              -
                                lat: 11.556978868
                                lon: 4.015151433
                    items:
                      type: object
                      properties:
                        gid:
                          type: integer
                          example: 1683577603
                        jurisd_local_id:
                          type: integer
                          example: 20904
                        l:
                          type: integer
                          example: 130
                        code_b32nvu:
                          type: string
                          example: FQS3
                        geom:
                          type: string
                          example: 0103000020787F000001000000050000000000000070EC274100000000581D1B4100000000B0EC274100000000581D1B4100000000B0EC274100000000D81D1B410000000070EC274100000000D81D1B410000000070EC274100000000581D1B41
                        centroide:
                          type: object
                          properties:
                            type:
                              type: string
                              example: Point
                            coordinates:
                              type: object
                              properties:
                                lat:
                                  type: number
                                  example: 11.557123313
                                lon:
                                  type: number
                                  example: 4.015295585
                        polygon:
                          type: object
                          properties:
                            type:
                              type: string
                              example: Polygon
                            coordinates:
                              type: array
                              example:
                                -
                                  -
                                    lat: 11.556978868
                                    lon: 4.015151433
                                  -
                                    lat: 11.557266857
                                    lon: 4.015150528
                                  -
                                    lat: 11.557267758
                                    lon: 4.015439738
                                  -
                                    lat: 11.556979768
                                    lon: 4.015440642
                                  -
                                    lat: 11.556978868
                                    lon: 4.015151433
                              items:
                                type: array
        404:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The geocode for latitude : 4.015296 and longitude : 11.557123 not found'
                  error: NOT_FOUND_GEOCODE
                  status: 404
                properties:
                  message:
                    type: string
                    example: 'The geocode for latitude : 4.015296 and longitude : 11.557123 not found'
                  error:
                    type: string
                    example: NOT_FOUND_GEOCODE
                  status:
                    type: integer
                    example: 404
      tags:
        - Endpoints
      security: []
  /api/geocode/multi-coordinates:
    post:
      summary: 'Multipoint geocodes'
      operationId: multipointGeocodes
      description: "This endpoint is used to make a request with an array of points\nThe return values is an array of the geocode."
      parameters: []
      responses:
        200:
          description: ''
          content:
            text/plain:
              schema:
                type: string
                example: "{\n    \"data\": [\n        {\n          \"point\" : {\n             \"longitude\": 11.557123,\n             \"latitude\": 4.015296\n           }\n          \"geocode\" : {\n              \"jurisd_local_id\": 20904,\n              \"code_b32nvu\": \"FQS3\",\n              \"l\": 130,\n              \"polygon\": {\n                 \"type\": \"Polygon\",\n                \"coordinates\": [\n                    [\n                        {\n                            \"lon\": \"11.557095\",\n                            \"lat\": \"4.052170\"\n                        },\n                        {\n                            \"lon\": \"11.557096\",\n                            \"lat\": \"4.052459\"\n                        },\n                        {\n                            \"lon\": \"11.557384\",\n                            \"lat\": \"4.052459\"\n                        },\n                        {\n                            \"lon\": \"11.557383\",\n                            \"lat\": \"4.052169\"\n                        },\n                        {\n                            \"lon\": \"11.557095\",\n                            \"lat\": \"4.052170\"\n                        }\n                    ]\n                ]\n            },\n            \"centroide\": {\n                \"type\": \"Point\",\n                \"coordinates\": {\n                    \"lon\": \"11.557240\",\n                    \"lat\": \"4.052314\"\n                }\n            },\n            \"city\": {\n                \"jurisd_local_id\": 20904,\n                \"city\": \"Soa\",\n                \"iso_label\": \"CM-SOA\",\n                \"lon\": \"11.55\",\n                \"lat\": \"3.95\",\n                \"country_id\": 1,\n                \"created_at\": \"2024-10-03T14:59:54.000000Z\",\n                \"updated_at\": \"2024-10-03T14:59:54.000000Z\"\n            }\n        }\n      }\n    ]\n}"
        404:
          description: ''
          content:
            text/plain:
              schema:
                type: string
                example: "{\n    \"data\": [\n        {\n          \"point\" : {\n             \"longitude\": 11.557123,\n             \"latitude\": 4.015296\n           }\n          \"geocode\" : 404\n        }\n      }\n    ]\n}"
      tags:
        - Endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                points:
                  type: array
                  description: 'An array of points to geocode. Each point should have a latitude and longitude.'
                  example:
                    -
                      longitude: 11.557123
                      latitude: 4.015296
                    -
                      longitude: -74.006
                      latitude: 40.7128
                  items:
                    type: string
                level:
                  type: integer
                  description: "The level of the polygon to retrieve. Here are the correspondances of level values.\nAn example of JSON request into the server\n\n<textarea style=\"width:100%\" rows=\"10\" readonly>\n{\n \"level\": 180,\n   \"points\": [\n       {\n           \"longitude\": 11.557123,\n           \"latitude\": 4.015296\n       },\n       {\n           \"longitude\": 1.557123,\n           \"latitude\": 4.015296\n       }\n   ]\n}\n</textarea>"
                  example: 155
              required:
                - points
      security: []
  '/api/geocode/code/{code}/{jurisd_local_id}':
    get:
      summary: 'Geocoding from Banoc Code'
      operationId: geocodingFromBanocCode
      description: 'This method make a search with banoc code, full or short and the jurisd_local_id that we need to check the city of the banoc code'
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      jurisd_local_id: 20904
                      code_b32nvu: FQS3
                      l: 130
                      polygon:
                        type: Polygon
                        coordinates:
                          -
                            -
                              lon: '11.557095'
                              lat: '4.052170'
                            -
                              lon: '11.557096'
                              lat: '4.052459'
                            -
                              lon: '11.557384'
                              lat: '4.052459'
                            -
                              lon: '11.557383'
                              lat: '4.052169'
                            -
                              lon: '11.557095'
                              lat: '4.052170'
                      centroide:
                        type: Point
                        coordinates:
                          lon: '11.557240'
                          lat: '4.052314'
                      city:
                        jurisd_local_id: 20904
                        city: Soa
                        iso_label: CM-SOA
                        lon: '11.55'
                        lat: '3.95'
                        country_id: 1
                        created_at: '2024-10-03T14:59:54.000000Z'
                        updated_at: '2024-10-03T14:59:54.000000Z'
                properties:
                  data:
                    type: array
                    example:
                      -
                        jurisd_local_id: 20904
                        code_b32nvu: FQS3
                        l: 130
                        polygon:
                          type: Polygon
                          coordinates:
                            -
                              -
                                lon: '11.557095'
                                lat: '4.052170'
                              -
                                lon: '11.557096'
                                lat: '4.052459'
                              -
                                lon: '11.557384'
                                lat: '4.052459'
                              -
                                lon: '11.557383'
                                lat: '4.052169'
                              -
                                lon: '11.557095'
                                lat: '4.052170'
                        centroide:
                          type: Point
                          coordinates:
                            lon: '11.557240'
                            lat: '4.052314'
                        city:
                          jurisd_local_id: 20904
                          city: Soa
                          iso_label: CM-SOA
                          lon: '11.55'
                          lat: '3.95'
                          country_id: 1
                          created_at: '2024-10-03T14:59:54.000000Z'
                          updated_at: '2024-10-03T14:59:54.000000Z'
                    items:
                      type: object
                      properties:
                        jurisd_local_id:
                          type: integer
                          example: 20904
                        code_b32nvu:
                          type: string
                          example: FQS3
                        l:
                          type: integer
                          example: 130
                        polygon:
                          type: object
                          properties:
                            type:
                              type: string
                              example: Polygon
                            coordinates:
                              type: array
                              example:
                                -
                                  -
                                    lon: '11.557095'
                                    lat: '4.052170'
                                  -
                                    lon: '11.557096'
                                    lat: '4.052459'
                                  -
                                    lon: '11.557384'
                                    lat: '4.052459'
                                  -
                                    lon: '11.557383'
                                    lat: '4.052169'
                                  -
                                    lon: '11.557095'
                                    lat: '4.052170'
                              items:
                                type: array
                        centroide:
                          type: object
                          properties:
                            type:
                              type: string
                              example: Point
                            coordinates:
                              type: object
                              properties:
                                lon:
                                  type: string
                                  example: '11.557240'
                                lat:
                                  type: string
                                  example: '4.052314'
                        city:
                          type: object
                          properties:
                            jurisd_local_id:
                              type: integer
                              example: 20904
                            city:
                              type: string
                              example: Soa
                            iso_label:
                              type: string
                              example: CM-SOA
                            lon:
                              type: string
                              example: '11.55'
                            lat:
                              type: string
                              example: '3.95'
                            country_id:
                              type: integer
                              example: 1
                            created_at:
                              type: string
                              example: '2024-10-03T14:59:54.000000Z'
                            updated_at:
                              type: string
                              example: '2024-10-03T14:59:54.000000Z'
        404:
          description: ''
          content:
            text/plain:
              schema:
                type: string
                example: "{\n\"message\": \"The geocode from code \"FQS3\" is not found\",\n \"error\": \"NOT_FOUND_GEOCODE\",\n  \"status\": 404\n}"
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: code
        description: 'Optional parameter. The banoc code, full or short.'
        required: true
        schema:
          type: string
        examples:
          omitted:
            summary: 'When the value is omitted'
            value: ''
          present:
            summary: 'When the value is present'
            value: FQS3
      -
        in: path
        name: jurisd_local_id
        description: 'Optional parameter. The jurisd_lolal_id for the city.'
        required: true
        schema:
          type: number
        examples:
          omitted:
            summary: 'When the value is omitted'
            value: ''
          present:
            summary: 'When the value is present'
            value: 20904.0
  /api/geocode/all:
    get:
      summary: 'All occurence'
      operationId: allOccurence
      description: 'API for returning all possible results, from BANOC Code, Nominatim or City lists'
      parameters:
        -
          in: query
          name: q
          description: 'The query to search.'
          example: SOA
          required: true
          schema:
            type: string
            description: 'The query to search.'
            example: SOA
        -
          in: query
          name: format
          description: 'List of the format needed, possible value are full,banoc,city,address. Default to full.'
          example: 'city,banoc'
          required: false
          schema:
            type: string
            description: 'List of the format needed, possible value are full,banoc,city,address. Default to full.'
            example: 'city,banoc'
        -
          in: query
          name: jurisd_local_id
          description: 'The jurisd_local_id for the city, we need it if we make request with banoc format.'
          example: 20904
          required: false
          schema:
            type: integer
            description: 'The jurisd_local_id for the city, we need it if we make request with banoc format.'
            example: 20904
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  cities:
                    -
                      jurisd_local_id: 20904
                      city: Soa
                      iso_label: CM-SOA
                      lon: '11.55'
                      lat: '3.95'
                      country_id: 1
                      created_at: '2024-10-03T14:59:54.000000Z'
                      updated_at: '2024-10-03T14:59:54.000000Z'
                      l: 80
                      country:
                        id: 1
                        name: Cameroun
                        created_at: '2024-09-06T13:58:23.000000Z'
                        updated_at: '2024-09-06T13:58:23.000000Z'
                  banoc_codes: []
                properties:
                  cities:
                    type: array
                    example:
                      -
                        jurisd_local_id: 20904
                        city: Soa
                        iso_label: CM-SOA
                        lon: '11.55'
                        lat: '3.95'
                        country_id: 1
                        created_at: '2024-10-03T14:59:54.000000Z'
                        updated_at: '2024-10-03T14:59:54.000000Z'
                        l: 80
                        country:
                          id: 1
                          name: Cameroun
                          created_at: '2024-09-06T13:58:23.000000Z'
                          updated_at: '2024-09-06T13:58:23.000000Z'
                    items:
                      type: object
                      properties:
                        jurisd_local_id:
                          type: integer
                          example: 20904
                        city:
                          type: string
                          example: Soa
                        iso_label:
                          type: string
                          example: CM-SOA
                        lon:
                          type: string
                          example: '11.55'
                        lat:
                          type: string
                          example: '3.95'
                        country_id:
                          type: integer
                          example: 1
                        created_at:
                          type: string
                          example: '2024-10-03T14:59:54.000000Z'
                        updated_at:
                          type: string
                          example: '2024-10-03T14:59:54.000000Z'
                        l:
                          type: integer
                          example: 80
                        country:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: Cameroun
                            created_at:
                              type: string
                              example: '2024-09-06T13:58:23.000000Z'
                            updated_at:
                              type: string
                              example: '2024-09-06T13:58:23.000000Z'
                  banoc_codes:
                    type: array
                    example: []
      tags:
        - Endpoints
      security: []
tags:
  -
    name: Endpoints
    description: ''
