Gender API Country Of Origin API

openapi: 3.2.0
info:
  version: '2.1'
  title: Gender-API.com Country Of Origin API
  description: Gender-API hilft dir herauszufinden, ob ein Vorname mehr von männlichen oder weiblichen Personen benutzt wird.
servers:
- url: https://gender-api.com/v2
  description: Main (production) server
security:
- bearerToken: []
tags:
- name: Country Of Origin
paths:
  /country-of-origin:
    post:
      summary: Get a name's country of origin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CountryOfOriginRequestModel'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountryOfOriginResultModel'
        '400':
          $ref: '#/components/responses/HttpError'
        '401':
          $ref: '#/components/responses/LimitExceededError'
      tags:
      - Country Of Origin
      operationId: postCountryOfOrigin
      x-operation-id-source: derived
components:
  schemas:
    CountryOfOriginRequestModel:
      type: object
      properties:
        first_name:
          type: string
          example: Johanna
        full_name:
          type: string
          example: null
        email:
          type: string
          example: null
    CountryOfOriginResultModel:
      type: object
      properties:
        input:
          description: The submitted payload
          properties:
            first_name:
              type: string
        details:
          properties:
            credits_used:
              type: integer
              description: The amount of credits used for this query
            duration:
              type: string
              description: Time the server needed to process the request
            samples:
              type: integer
              description: Number of records found in our database which match your request
            country:
              type: string
              description: The country we found
            first_name_sanitized:
              type: string
              description: The name after we applied our normalizer to it
        result_found:
          type: boolean
          description: True if we were able to query a gender for the given name
        country_of_origin:
          type: array
          items:
            type: object
            properties:
              country_name:
                type: string
                example: Germany
              country:
                type: string
                example: DE
              probability:
                type: number
                description: This value (between 0 and 1) determines how sure we are, that this name comes from this country
              continental_region:
                type: string
                example: Europe
              statistical_region:
                type: string
                example: Western Europe
        country_of_origin_map_url:
          type: string
          description: URL to an interactive map about this name
        first_name:
          type: string
          description: The first name we used for the genderization
        probability:
          type: number
          format: float
          description: This value (between 0 and 1) determines the reliability of our database. A value of 1 means that the results on your gender request are 100% accurate.
        gender:
          type: string
          example: female
          description: 'Possible values: male, female, unknown (if we have the same amount of male and female samples for this name, the API will return unknown here)'
      example:
        input:
          first_name: Johanna
        details:
          credits_used: 2
          duration: 210ms
          samples: 3826
          country: null
          first_name_sanitized: johanna
        result_found: true
        country_of_origin:
        - country_name: Germany
          country: DE
          probability: 0.53
          continental_region: Europe
          statistical_region: Western Europe
        - country_name: Finland
          country: FI
          probability: 0.26
          continental_region: Europe
          statistical_region: Northern Europe
        - country_name: Belgium
          country: BE
          probability: 0.16
          continental_region: Europe
          statistical_region: Western Europe
        - country_name: United States
          country: US
          probability: 0.03
          continental_region: Americas
          statistical_region: Northern America
        - country_name: Spain
          country: ES
          probability: 0.02
          continental_region: Europe
          statistical_region: Southern Europe
        country_of_origin_map_url: http://localhost/en/map/7/f43185621c3e4c9c
        first_name: Johanna
        probability: 0.99
        gender: female
    ErrorModel:
      type: object
      properties:
        status:
          type: integer
          description: error code.
          example: 400
        type:
          type: string
          description: Link to the error description.
          example: https://gender-api.com/en/api-docs/v2/index/problem-details/invalid-country-code
        title:
          type: string
          description: error id.
          example: invalid-country-code
        detail:
          type: string
          description: human readable error description
          example: The given country code is not valid. You can find a list of valid country codes in our API docs.
    LimitExceededModel:
      allOf:
      - $ref: '#/components/schemas/ErrorModel'
      properties:
        status:
          example: 401
        type:
          example: https://gender-api.com/en/api-docs/v2/index/problem-details/limit-exceeded
        title:
          example: limit-exceeded
        detail:
          example: Your account has no requests left. This is not an authentication error, and retrying will not help. Buy more requests at https://gender-api.com/en/pricing?from=api-limit
        upgrade_url:
          type: string
          format: uri
          description: Link to the pricing page where more requests can be bought. Show it to the person who manages the account. Only present when title is limit-exceeded.
          example: https://gender-api.com/en/pricing?from=api-limit
  responses:
    HttpError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorModel'
      description: " parameter-first-name-invalid: The \"first_name\" parameter is invalid. The parameter can only be a string with a length from 1 to 50 chars. \n\n parameter-full-name-invalid: The \"full_name\" parameter is invalid. The parameter can only be a string with a length from 3 to 100 chars. \n\n parameter-email-invalid: The \"email\" parameter is invalid. The parameter can only be a string with a length from 3 to 100 chars and must be a valid email address. \n\n invalid-key: Invalid API key. You can find your personal API key in your account. \n\n invalid-country-code: The given country code is not valid. You can find a list of valid country codes in our API docs. \n\n invalid-ip-address: The given ip address is not valid. Please provide either a valid IPv4 or an IPv6 address. \n\n invalid-json: The JSON from the post data is invalid \n\n invalid-locale: The given locale is not valid. You can find a list of valid country codes in our API docs. \n\n invalid-id: The given id is not valid. An id can be either an integer or a string with 50 chars at max. \n\n mandatory-parameter-missing: Mandatory parameter missing. Either first_name, full_name or email must be set. \n\n content-type-missing: Content-Type missing. Please add a \"Content-Type: application/json\" to your API call. \n\n missing-json: We weren't able to find a json body in your API call. Please make sure the body is sent with a POST request to our API endpoint. \n\n too-many-queries: Too many queries in a single API call. authorization-header-missing: Your query misses the \"Authorization\" header with the bearer token. \n\n invalid-auth-token: Invalid authentication token provided. Please log in to your account to find a list of valid tokens or to create a new one. \n\n "
    LimitExceededError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LimitExceededModel'
      description: limit-exceeded - Your account has no requests left. The status stays 401 for backwards compatibility, but this is not an authentication error and retrying will not help. The response carries an upgrade_url field with the link to buy more requests.
  securitySchemes:
    bearerToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Get an API key here: [https://gender-api.com/en/account/auth-tokens](https://gender-api.com/en/account/auth-tokens)'
x-provenance:
  method: harvested
  publisher: Gender API
  source: https://gender-api.com/openapi/openapi.yml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)