api.yaml

openapi: 3.0.0
servers: 
  - url: https://bsaexcedti.api.geosure.tech
    description: development
  - url: https://bsaexcedti.api.geosure.tech
    description: staging
  - url: https://bsaexcedti.api.geosure.tech
    description: production
info:
  description: GeoSure API
  version: "3.0.1"
  title: GeoSure API
  contact:
    email: [email protected]
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
paths:
  /score/:
    get:
      tags:
      - score
      summary: scores for locations including personalization
      operationId: score
      description: |
        By passing in a bounding box, you can retrieve geosure scores. Optionally pass in personal parameters for a personalized score.
      parameters:
        - in: query
          name: bbox
          description:  "Format: -180.0,-90.0,180.0,90.0 Required unless id_list is present."
          required: false
          schema:
            type: string
        - in: query
          name: id_list
          description:  "Return information only for the set of records that match the requested id. Format: 2,4,5"
          required: false
          schema:
            type: string
        - in: query
          name: access_token
          description:  "Access token"
          required: true
          schema:
            type: string
        - in: query
          name: travel_class
          description:  "Travel Class"
          required: false
          schema:
            type: string
            enum:
              - economy
              - business
              - first
        - in: query
          name: travel_status
          description:  "Travel Status/Usually Travels"
          required: false
          schema:
            type: string
            enum:
              - alone
              - companion
              - group
        - in: query
          name: familiarity
          description:  "Familiarity"
          required: false
          schema:
            type: string
            enum:
              - little
              - moderate
              - extensive
        - in: query
          name: citizenship
          description:  "Country of Citizenship"
          required: false
          schema:
            type: string
        - in: query
          name: birth
          description:  "Birth year"
          required: false
          schema:
            type: string
        - in: query
          name: gender
          description:  "Gender"
          required: false
          schema:
            type: string
            enum:
              - male
              - female
              - other
        - in: query
          name: languages
          description:  "Comma separated list of languages in order of proficiency (two characters code)"
          example: "en,es"
          required: false
          schema:
            type: string
      responses:
        '200':
          description: search results matching criteria
          content:
            application/geo+json-seq:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Score'
        '400':
          description: bad input parameter
        '401':
          description: unathorized
  /search/:
    get:
      tags:
      - search
      summary: search for information based on Mapbox geocoding apis 
      operationId: search
      description: |
        Forward and reverse geocoding.
      parameters:
        - in: query
          name: q
          description:  search term
          example:  soledad
          required: true
          schema:
            type: string
        - in: query
          name: access_token
          description:  "Access token"
          required: true
          schema:
            type: string 
        - in: query
          name: geocoding
          description:  "Indicate forward or reverse geocoding. Allowed values are `forward` and `reverse`. [default: `forward`]"
          example:  "forward"
          required: false
          schema:
            type: string
        - in: query
          name: bbox
          description:  "Restrict forward geocoding to specified bounding box,given in  minX,minY,maxX,maxY coordinates."
          required: false
          schema:
            type: string
        - in: query
          name: lat
          description:  "Bias results toward this latitude (decimal degrees). `lon` is also required."
          required: false
          schema:
            type: string
        - in: query
          name: lon
          description:  "Bias results toward this longitude (decimal degrees). `lat` is also required."
          required: false
          schema:
            type: string    
        - in: query
          name: country
          description:  "Restrict forward geocoding to specified country codes,comma separated."
          required: false
          schema:
            type: string 
        - in: query
          name: language
          description:  "Specify the language to use for response text and, for forward geocoding, query result weighting"
          required: false
          schema:
            type: string
        - in: query
          name: types
          description:  "Filter results by one or more feature types. Options are  `country` ,  `region` , `postcode` ,  `district` ,  `place` ,  `locality` ,  `neighborhood` ,  `address` ,  `poi` , and  `poi.landmark` . Note that  `poi.landmark` returns a subset of the results returned by  poi . Multiple options can be comma-separated."
          required: false
          schema:
            type: string
        - in: query
          name: mode
          description:  "Use a different mapbox dataset to search. Note: Our account does not have permanent places enabled."
          required: false
          schema:
            type: string
      responses:
        '200':
          description: search results matching criteria
          content:
            application/geo+json-seq:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Location'
        '400':
          description: bad input parameter
        '401':
          description: unathorized
      security:
      - access_token: []
  /report/:
    post:
      tags:
      - reports
      summary: report experience
      operationId: report
      description: |
        Report your experience on a location
      parameters:
        - in: query
          name: access_token
          description:  "Access token"
          required: true
          schema:
            type: string
        - in: post
          name: geometry
          required: true
          $ref: '#/components/schemas/Geometry'
        - in: post
          name: properties
          required: true
          $ref: '#/components/schemas/ReportProperties'
      responses:
        '200':
          description: report successfully saved
        '400':
          description: bad input parameter
        '401':
          description: unathorized
      security:
      - access_token: []
  /options/:
    get:
      tags:
      - options
      summary: Gets list of personalization options
      operationId: options
      description: |
       Get a list of options for the app.
          languages
          https://github.com/django/django/blob/d6859a14891f028dde8c6d27fb2960ef9984a072/django/conf/locale/__init__.py
          countries
          https://github.com/SmileyChris/django-countries/blob/master/django_countries/data.py
      responses:
        '200':
          description: search results matching criteria
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Options'
        '401':
          description: unathorized
      security:
      - access_token: []
components:
  schemas:
    Score:
      type: object
      required:
        - properties
        - geometry
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          example: "Feature"
        properties:
          $ref: '#/components/schemas/ScoreProperties'
        geometry:
          $ref: '#/components/schemas/Geometry'
    ScoreProperties:
      required:
        - name
      properties:
        province:
          type: string
          example: Atlantico
        region:
          type: string
          example: South America
        district:
          type: string
          example: Overall
        city:
          type: string
          example: Soledad
        neighborhood:
          type: string
          example: subset of city
        population:
          type: integer
          example: 550400
        distance:
          type: number
          example: 0.008441933464499462
      type: object
    Geometry:
      required:
        - name
      properties:
        type:
          type: string
          example: 'Point'
        coordinates:
          type: array
          example: "[-74.75, -10.916667]"
      type: object
    Location:
      type: object
      required:
        - properties
        - geometry
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          example: "Feature"
        properties:
          $ref: '#/components/schemas/LocationProperties'
        geometry:
          $ref: '#/components/schemas/Geometry'
    LocationProperties:
      required:
        - wikidata
      properties:
        wikidata:
          type: string
          example: Q767071
      type: object
    ReportProperties:
      type: object
      properties:
        type:
          type: string
        sentiment:
          type: string
        category:
          type: string
        subcategory:
          type: string
        time:
          type: string
    Options:
      type: object
      properties:
        countries:
          $ref: '#/components/schemas/Countries'
        languages:
          $ref: '#/components/schemas/Languages'
    Country:
      type: object
      description: The countries of the world
      properties:
        code:
          type: string
          format: two letter code
          description: iso3166 two letter code. https://www.iso.org/obp
          example: bo
        name_local:
          type: string
          example: Bolivia (Estado Plurinacional de)
        name:
          type: string
          example: Bolivia (Plurinational State of)
    Countries:
      type: array
      items:
        $ref: '#/components/schemas/Country'
    Language:
      type: object
      description: The languages of the world
      properties:
        code:
          type: string
          format: es
          description: This supports advanced things like es-co for Colombian Spanish.
        name:
           type: string
           example: Spanish
        name_local:
          type: string
          example: Español
        bidi:
          type: boolean
          example: False
        
    Languages:
      type: array
      items:
        $ref: '#/components/schemas/Language'
    Article:
      type: object
      description: The languages of the world
      properties:
        tbd:
          type: string
          description: models crom from newsapi.org
    News:
      type: array
      items:
        $ref: '#/components/schemas/Article'