---
tags: 
  - Points with Displacements
description:
  This endpoint is the same as <strong>/displacements</strong>, but will return points' displacements (and their calculated velocities) set to use to the most recent number of months (integer).  The velocity over the complete time period available in the database is also returned as `velocity_original` for comparison. The recalculated velocity value used for colouring points in `/tile` endpoints is also included as `velocity_averaged`, which approximates the velocity using displacements averaged over each 3-month period.<br/>
  This is a shortcut to setting the `start_date` and `end_date` of a <strong>/displacements</strong> request.<br/>
  If the `months` value is not an integer, it is ignored.<br/>
  `date_range` is returned in the results to show the `start_date` and `end_date` used in the request.<br/><br/>

  Returns the same as <strong>/points</strong>, but with displacements included.  Returns points within the provided GeoJSON polygon provided in the body.
  <br/><strong>REQUIRED</strong> `coordinates` in SRID=4326.  Polygons must be single and simple, and within containing brackets (e.g. `[[[x1,y1], [x2,y2], [x3,y3] [x1, y1]]]`)
  <br/><strong>REQUIRED</strong> `type` must be be "Polygon" or "Point".
  <br/><strong>OPTIONAL</strong> `radius` (metres). <strong>Required if `type` is "Point"</strong>, and ignored otherwise.
  <br/><strong>OPTIONAL</strong> `layers` array of strings to choose the layers.  Defaults to all layers the user has access to if not set.
  <br/><strong>OPTIONAL</strong> `limit` restrict the number of points in the response.  There is a hard limit of 1500.  Points within the centre of the polygon are returned, working outwards until the limit is reached.
  <br/><strong>OPTIONAL</strong> `suppress_geometry` boolean to control whether the requested polygon is returned in the response.
  <br/><strong>OPTIONAL (ignored if provided `months` value is valid)</strong> query params `start_date`, `end_date` integers (format <strong>YYYYMMDD</strong>) to recalculate the velocity value.  If invalid dates are entered, they are ignored (e.g. end date before start date).  If the user doesn't have access to the end date, the latest date they have access to will be used instead.  An additional `velocity_original` attribute will be returned with each point to show the velocity over the full time period when the `velocity` has been recalculated. The recalculated velocity value used for colouring points in `/tile` endpoints is also included as `velocity_averaged`, which approximates the velocity using displacements averaged over each 3-month period.
  <br/><br/>If the User does not have access to the geometry, no points are returned.
  <br/><br/><strong>This endpoint is not intended for systematically retrieving data over very large areas, and is rate-limited.  The following options may be more suitable:</strong>
  <ul>
    <li>The `/tile` endpoints, which use colour-coded velocity values that are derived from displacements, can be used to quickly identify your area of interest for wide areas.</li>
    <li>The `/point` endpoint will return the location of points within an area of interest without displacements, and is therefore faster than the `/displacements` endpoint to retrieve locations and velocities of points.</li>
    <li><a href="mailto:contact@satsense.com?subject=API%20Displacements">Contact us</a> to discuss other options that may be more suitable for your needs - it may be that there are more appropriate solutions than what an API can provide.</li>
  </ul>

  <br/><br/>Additional optional attributes will be returned if these are present in the database.  These values are not present in every location.
  <br/><strong>cycle_slips</strong> (integer)
  <br/><strong>av_coherence</strong> (float)
  <br/><strong>height</strong> (float)
  <br/><strong>delta_quality_3</strong> (float)
  <br/><strong>delta_quality_6</strong> (float)
  <br/><strong>delta_velocity_3</strong> (float)
  <br/><strong>delta_velocity_6</strong> (float)
  <br/><strong>scatter</strong> (string - 'PS' or 'DS')
parameters:
  - in: header
    name: Authorization
    type: string
    required: true
  - in: body
    name: body
    type: object
    required: true
    schema:
      example: {
      "type": "Point",
      "radius": 10,
      "coordinates": 
              [
                  -0.0037068128585815434,
                  51.51954215811389
              ],
      "suppress_geometry": false,
      "layers": ["asc", "desc"],
      "limit": 1
      }
  - in: query
    name: start_date
    type: int
    required: false
  - in: query
    name: end_date
    type: int
    required: false
produces: 
  - 'application/json'
responses:
  200:
    schema:
      type: object
      properties:
        date_range:
          type: object
          example: { "start_date": "2025-01-01 00:00:00", "end_date": "2022-01-01 00:00:00" }
        geometry:
          type: object
          example: { "type": "Point", "coordinates": [-0.0037068128585815434, 51.51954215811389], "suppress_geometry": false, "layers": ["asc", "desc"] }
        points:
          type: array
          example: [{ "coordinates": [0, 1], "displacements": {"20230101": 1.1, "20230102": 2.2}, "id": 1, "layer": "asc", "name": "123A_00001_00001_0001_0001", "orbit": "asc", "rmse": 1.1, "velocity": 0.6, "velocity_original": 1.2, "velocity_averaged": 0.7 }]
  204:
    schema:
      type: object

  401:
    schema:
      type: object
      properties:
        error:
          type: string
          example: 'User not authorised'

