Destinations

Destinations represent the location details for tasks, including exact coordinate and address information.

Create destination

Body parameters

NameTypeDescription
addressobjectThe destination’s street address details.
locationarrayOptional. The [ longitude, latitude ] geographic coordinates. If missing, the API will geocode based on the address details provided. Note that geocoding may slightly modify the format of the address properties. address.unparsed cannot be provided if you are also including a location.
notesstringOptional. Notes about the destination.
optionsobjectOptional. Includes the language options.
curl -X POST "https://store.bponi.com/api/v2/destinations" \
       -u "cd3b3de84cc1ee040bf06512d233719c:" \
       -d '{"address":{"number":"543","street":"Howard St","apartment":"5th Floor","city":"San Francisco","state":"CA","country":"USA"},"notes":"Don\'t forget to check out the epic rooftop."}'
1
2
3
{
  "id": "JLn6ZoYGZWn2wB2HaR9glsqB",
  "timeCreated": 1455156663000,
  "timeLastModified": 1455156663896,
  "location": [
    -122.3965731,
    37.7875728
  ],
  "address": {
    "apartment": "5th Floor",
    "state": "California",
    "postalCode": "94105",
    "country": "United States",
    "city": "San Francisco",
    "street": "Howard Street",
    "number": "543"
  },
  "notes": "Don't forget to check out the epic rooftop.",
  "metadata": []
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

An address has the following properties:

NameTypeDescription
namestringOptional. A name associated with this address, for example, "Transamerica Pyramid".
numberstringThe number component of this address, it may also contain letters.
streetstringThe name of the street.
apartmentstringOptional. The suite or apartment number, or any additional relevant information.
citystringThe name of the municipality.
statestringOptional. The name of the state, province or jurisdiction.
postalCodestringOptional. The postal or zip code.
countrystringThe name of the country.
unparsedstringOptional. A complete address specified in a single, unparsed string where the various elements are separated by commas. If present, all other address properties will be ignored (with the exception of name and apartment). In some countries, you may skip most address details (like city or state) if you provide a valid postalCode: for example, 543 Howard St, 94105, USA will be geocoded correctly.
curl -X POST "https://store.bponi.com/api/v2/destinations" \
       -u "cd3b3de84cc1ee040bf06512d233719c:" \
       -d '{"address":{"unparsed":"666 Post St, SF, CA, USA"}}'
1
2
3
{
  "id": "barP8D82zGyzd~7~74dSCDV1",
  "timeCreated": 1455156664000,
  "timeLastModified": 1455156664297,
  "location": [
    -122.4128901,
    37.787933
  ],
  "address": {
    "apartment": "",
    "state": "California",
    "postalCode": "94109",
    "country": "United States",
    "city": "San Francisco",
    "street": "Post Street",
    "number": "666"
  },
  "notes": "",
  "metadata": []
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

Create destination with complete address details, parsed, see examples of creating destinations with parsed addresses in the side bar:

Create destination using an unparsed address, see examples of unparsed addresses in the side bar:

Create destination with location coordinates must include parsed address.city and address.country components at the minimum. See examples of locations addresses in the side bar:

An options has the following properties:

NameTypeDescription
languagestringOptional. The language options follows the ISO Standard of 2-letters country code.

Get single destination

When attempting to access a destination endpoint that does not belong to your organization, an error message will be thrown stating that the request is outside of your permission scope.

curl -X GET "https://store.bponi.com/api/v2/destinations/0i~RR0SUIculbRFsIse6MENg" \
       -u "cd3b3de84cc1ee040bf06512d233719c:"
1
2
{
  "id": "0i~RR0SUIculbRFsIse6MENg",
  "timeCreated": 1455156664000,
  "timeLastModified": 1455156664697,
  "location": [
    -122.4052935,
    37.7721234
  ],
  "address": {
    "apartment": "",
    "state": "California",
    "postalCode": "94103",
    "country": "United States",
    "city": "San Francisco",
    "street": "Brannan Street",
    "number": "888"
  },
  "notes": "",
  "metadata": []
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

Destination Address Warning:

Bponi Storeopen in new window destination has built-in address validation by querying major geocoding services to ensure address is as close to the input as possible. However, due to erroneous input or lack of address data, some addresses could be transformed due to reverse geocode process. Destination creation endpoint will now include warnings that are intended to alert the Driver or the Dispatchers that the input needs special attention. These warnings will be included in the warnings field. The warnings field is an array of strings.

  • MISMATCH_NUMBER: The resulting address number is different than the input address number
  • MISMATCH_POSTALCODE: The resulting postal code is different than the input address postal code
  • GEOMETRIC_CENTER: The address needs apartment number precision or additional inputs

Geometric Center: Currently, any apartment/office/business/mobile home complex are deemed as a geometric center. This means it's best to provide an apartment field to signify what is equivalent address 2 for Drivers' knowledge.

{
    "id": "u~v6vLzG95rtqxJyWpTs9HBO",
    "timeCreated": 1621452442000,
    "timeLastModified": 1621452442616,
    "location": [
        -120.435403,
        34.937994
    ],
    "address": {
        "apartment": "",
        "state": "California",
        "postalCode": "93454",
        "number": "1316",
        "street": "South Broadway",
        "city": "Santa Maria",
        "country": "United States"
    },
    "notes": "",
    "metadata": [],
    "googlePlaceId": "ChIJo8Iimp1s7IARWN1SlyhTMx0",
    "warnings": [
        "GEOMETRIC_CENTER"
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
    "id": "IxcBp8OdNV0vP2eD2o5S0nsw",
    "timeCreated": 1621452422000,
    "timeLastModified": 1621452422809,
    "location": [
        -79.2085146,
        43.1881771
    ],
    "address": {
        "apartment": "",
        "state": "Ontario",
        "postalCode": "L2M 4G5",
        "number": "3",
        "street": "Leaside Drive",
        "city": "St. Catharines",
        "country": "Canada"
    },
    "notes": "",
    "metadata": [],
    "googlePlaceId": "ChIJ25F7pKNQ04kRlBqn9IZcmcE",
    "warnings": [
        "MISMATCH_NUMBER"
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
    "id": "2tm3DZ3oaFELxOXfrldYHC7M",
    "timeCreated": 1621451681000,
    "timeLastModified": 1621451681044,
    "location": [
        -79.2066056,
        43.1889085
    ],
    "address": {
        "apartment": "",
        "state": "Ontario",
        "postalCode": "L2M 4G2",
        "number": "33",
        "street": "Leaside Drive",
        "city": "St. Catharines",
        "country": "Canada"
    },
    "notes": "",
    "metadata": [],
    "googlePlaceId": "ChIJTacH86NQ04kR2aM8fiPyhBI",
    "warnings": [
        "MISMATCH_POSTALCODE"
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
Last Updated: 11/29/2021, 10:25:26 PM