Service areas¶

This API allows listing, retrieving, creating, updating, and deleting service areas. Service areas are identified by their UUID.

List Service Areas¶

GET /service_area/¶

List all service areas.

Sample request:

GET /service_area/ HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Accept: application/json

Sample response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "count": 100,
  "items": [
    {
      "name": "South Inner",
      "uuid": "01c9373d6d22438096503fe72a7c1612",
      "link": {
        "rel": "detail",
        "url": "https://api.fieldaware.net/service_area/01c9373d6d22438096503fe72a7c1612"
      }
    },
    {
      "name": "North Florida",
      "uuid": "01f359aabafb4ff28347bddd9a24f28a",
      "link": {
        "rel": "detail",
        "url": "https://api.fieldaware.net/service_area/01f359aabafb4ff28347bddd9a24f28a"
      }
    },
    {
      "name": "Key West",
      "uuid": "0274f3fa2e224e17ba9e6a36ce3f4b0a",
      "link": {
        "rel": "detail",
        "url": "https://api.fieldaware.net/service_area/0274f3fa2e224e17ba9e6a36ce3f4b0a"
      }
    }
  ],
  "page": 0,
  "pageSize": 3,
  "sortedBy": []
}

Query Parameters:

sortedBy – Available sorting criteria: name
name – A filtering value for service area name

Get Service Area¶

GET /service_area/(area_ref)¶

Retrieve a given service area.

Sample request:

GET /service_area/0274f3fa2e224e17ba9e6a36ce3f4b0a HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Accept: application/json

Sample response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "Yuge rectangle",
  "description": "Nice rectangular shape",
  "colour": "123132",
  "area": {
    "shape": "RECTANGLE",
    "geometry": {
      "ne": {"lat": 0, "lng": 0},
      "sw": {"lat": 1, "lng": 1}
    }
  }
}

Create Service Area¶

POST /service_area/¶

Create a new service area.

Sample request:

POST /task/ HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Accept: application/json

{
  "name": "Yuge rectangle",
  "description": "Nice rectangular shape",
  "colour": "123132",
  "area": {
    "shape": "RECTANGLE",
    "geometry": {
      "ne": {"lat": 0, "lng": 0},
      "sw": {"lat": 1, "lng": 1}
    }
  }
}

Request JSON Object:

name (string) – Name of the service area (required)
description (string) – Description of the service area
colour (string) – colour to visualize the area on a map, expressed with a HTML hex colour code. E.g. “FFFFFF” for white
area (obj) – mapping to define the shape of the service area

Sample response:

HTTP/1.1 201 Created
Content-Type: application/json

Update Service Area¶

PUT /service_area/(area_ref)¶

Update a given service area.

Sample request:

Same as Create Service Area, with all properties being optional.

PUT /service_area/00bd62a92a004faea233951510167cad HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 687fe20baeef448bb30db579139dad33
Accept: application/json

{
  "name": "Brooklyn"
}

Sample response:

HTTP/1.1 204 NO CONTENT

Delete Service Area¶

DELETE /service_area/(area_ref)¶

Delete a given service area.

Sample request:

DELETE /service_area/00bd62a92a004faea233951510167cad HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 687fe20baeef448bb30db579139dad33
Accept: application/json

Sample response:

HTTP/1.1 204 No Content

Defining Areas¶

Service areas define polygonal areas on a map. There are two kinds of valid service area shapes: rectangles and linear rings. These shapes are specified by providing a number of geographical coordinates (latitude, longitude) corresponding to the opposing corners of a rectangle, or the vertices of a polygon.

Rectangle

A rectangular shape is defined by two coordinates (latitude, longitude) that correspond with the North East and South West corners of the rectangle.

Sample payload for a rectangular service area

{
  "name": "Rectangular area",
  "description": "Nice rectangular shape",
  "colour": "FFFFFF",
  "area": {
    "shape": "RECTANGLE",
    "geometry": {
      "ne": {"lat": 0, "lng": 0},
      "sw": {"lat": 1, "lng": 1}
    }
  }
}

Linear ring

A linear ring defines a polygonal area from a collection of coordinates. The minimum number of vertices provided to define an area is three.

Sample payload for a linear ring area

{
  "name": "Triangular area",
  "description": "Nice rectangular shape",
  "colour": "CDCDCD",
  "area": {
    "shape": "LINEAR_RING",
    "geometry": [
      {"lat": 0, "lng": 0},
      {"lat": 1, "lng": 1},
      {"lat": 3, "lng": 2}
    ]
  }
}