openapi: 3.2.0 info: title: Geocoding and Search API v7 Signals API version: '7.155' description: This document describes the Geocoding and Search API. security: - Bearer: [] - ApiKey: [] tags: - name: Signals paths: /signals: servers: - url: https://signals.search.hereapi.com/v1 post: summary: Signals description: '**RESTRICTED** This endpoint receives user interaction data from previous search results to improve future result quality.' parameters: - $ref: '#/components/parameters/X-Request-ID' responses: '204': description: Empty response '400': description: 'Client error: request failed validation.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '405': description: 'Client error: http method not supported.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '413': description: 'Client error: request body exceeds size limit.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '415': description: 'Client error: request body has unsupported content type.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: 'Client error: Rate limit exceeded.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Temporary server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' requestBody: description: "Takes a newline-separated list of requests, following the URL query parameter syntax.\n\nEach line in the body informs the search backend about a user interaction. A typical call contains only one user interaction, but multiple can be provided at once.\nThe fields expected in each line are:\n\n* `version`: Defines the version of the payload (needs to be set to 1)\n\n* `action`: Specifies the user action. It must be one of the following values (any other value will lead to a 400):\n\n * `here:gs:action:call`: To be sent when the end-user uses the result phone number.\n * `here:gs:action:email`: To be sent when the end-user uses the result email address.\n * `here:gs:action:navigate-from`: To be sent when the end-user starts a navigation from the result item.\n * `here:gs:action:navigate-to`: To be sent when the end-user starts a navigation to the result item.\n * `here:gs:action:pin`: To be sent when the end-user bookmarks a result\n * `here:gs:action:tap`: To be sent when the end-user taps on the result displayed on a map.\n * `here:gs:action:view`: To be sent when the end-user selects a result in a result list.\n * `here:gs:action:share`: To be sent when the end-user shares/sends a result to another user or as a mail/PM.\n * `here:gs:action:visit`: To be sent when the end-user visits the result www contact.\n\n* `correlationId`: The value of the previous response `X-Correlation-ID` header on which the action is performed\n\n* `resourceId`: The ID value of the search result on which the action is performed.\n\n This is either:\n * `id` when the action occurs on a Lookup response\n * `items[].id` when the action occurs on any other endpoint\n\n* `rank`: The rank of the object in the response items array. The first result is at rank 0. It is always 0 when the action happens on a Lookup response.\n\nRecommended:\n\n* `timestamp`: (Recommended but optional) The Unix Epoch timestamp in milliseconds based on user interaction performed on the response item.\n\nExample payload to `POST /v1/signals`:\n```\nversion=1&resourceId=hrn:af:street:bYLa1RIXm08-g5lRgt0ebA&correlationId=22457435-efcf-46b9-8c87-62912f3f2f0&rank=0&action=here:gs:action:navigate-to×tamp=1692625661\n```\n" required: true content: text/plain; charset=UTF-8: schema: type: string example: version=1&resourceId=hrn:af:street:bYLa1RIXm08-g5lRgt0ebA&correlationId=22457435-efcf-46b9-8c87-62912f3f2f0c&rank=0&action=here:gs:action:navigate-to×tamp=1692625661 application/x-www-form-urlencoded: schema: type: string example: version=1&resourceId=hrn:af:street:bYLa1RIXm08-g5lRgt0ebA&correlationId=22457435-efcf-46b9-8c87-62912f3f2f0c&rank=0&action=here:gs:action:navigate-to×tamp=1692625661 tags: - Signals operationId: postSignals x-operation-id-source: derived components: schemas: ErrorResponse: type: object required: - status - title - correlationId - requestId properties: status: type: integer format: int32 description: The HTTP status code title: type: string description: Human-readable error description code: type: string description: Error code cause: type: string description: Human-readable explanation for the error action: type: string description: Human-readable action for the user correlationId: type: string description: Auto-generated ID univocally identifying this request requestId: type: string description: Request identifier provided by the user parameters: X-Request-ID: name: X-Request-ID description: 'Used to correlate requests with their responses within a customer''s application, for logging and error reporting. Format: Free string, but a valid UUIDv4 is recommended.' in: header required: false schema: type: string securitySchemes: Bearer: description: 'A token obtained from a separate endpoint using client credentials and an OAuth 1.0a HMAC-SHA256 signed request. For more information on how to get a bearer token, see the [Identity and Access Management Developer Guide](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/). ' type: http scheme: bearer bearerFormat: JWT ApiKey: description: 'A key generated specifically to authenticate API requests. For more information on how to get an API key, see the [Identity and Access Management Developer Guide](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/). ' type: apiKey name: apiKey in: query externalDocs: description: The developer guide, release notes, and migration guide are available here. url: https://www.here.com/docs/category/geocoding-search-v7