August 19

123cargo
API 2015
The scope of this document is to describe the 123cargo API and how
to use it for posting, updating, deleting and searching for loads and Version 0.55
trucks.
Global GET parameters limit and offset ........................................................................................ 3
Resource description .............................................................................................................................. 4
place .................................................................................................................................................... 4
Properties........................................................................................................................................ 4
truckType ............................................................................................................................................ 4
companyScoring.................................................................................................................................. 5
Properties........................................................................................................................................ 5
companyStatistics ............................................................................................................................... 5
Properties........................................................................................................................................ 5
company.............................................................................................................................................. 6
Properties........................................................................................................................................ 6
companySearch ................................................................................................................................... 6
Properties........................................................................................................................................ 6
site....................................................................................................................................................... 6
Properties........................................................................................................................................ 6
contact ................................................................................................................................................ 7
Properties........................................................................................................................................ 7
companyContact ................................................................................................................................. 7
Price .................................................................................................................................................... 7
Properties........................................................................................................................................ 7
load ..................................................................................................................................................... 7
Properties........................................................................................................................................ 7
loadSearch........................................................................................................................................... 8
Properties........................................................................................................................................ 8
truck .................................................................................................................................................... 9
truckSearch ......................................................................................................................................... 9
Properties...................................................................................................................................... 10
Request URIs ......................................................................................................................................... 11
/loads ................................................................................................................................................ 12
Methods summary ........................................................................................................................ 12
/searchloads ...................................................................................................................................... 12
Methods summary ........................................................................................................................ 12
/trucks ............................................................................................................................................... 13
Methods summary ........................................................................................................................ 13
 /searchtrucks .................................................................................................................................... 13
Methods summary ........................................................................................................................ 13
/companies ....................................................................................................................................... 14
Methods summary ........................................................................................................................ 14
/places ............................................................................................................................................... 14
Methods summary ........................................................................................................................ 14
Responses ............................................................................................................................................. 15
Change log............................................................................................................................................. 16
0.54 – 13.11.2014 ............................................................................................................................. 16
0.53 – 10.11.2014 ............................................................................................................................. 16
0.52 – 23.10.2014 ............................................................................................................................. 16
0.51 – 07.06.2014 ............................................................................................................................. 16
0.5 – 16.04.2014 ............................................................................................................................... 16
123cargo API specifications
123cargo API implements REST architectural style over HTTP with JSON data type.

The base URLs of the API are:

Live environment: https://www.bursatransport.com/api

Test environment: https://www.test.bursatransport.com/api

All URIs are relative to the base URL specified above unless otherwise noted. Be aware that URL of
the service may change and we highly recommend keeping them as configuration parameters in
your implementation.

All requests’ data are JSON encoded in the request body.

Authentication is done via HTTP Basic authentication.

Global GET parameters limit and offset

Those 2 parameters are used to retrieve a portion of results, just like in SQL.

Limit – limits the number of results returned up to a maximum of 50. Default is 50.

Offset – skips the first n results. Default is 0.

Resource description
Properties ending in [] represent arrays composed of multiple objects of the stated type.
Strings enclosed in <> represent input parameters.

Boolean values may be sent as 0/1 or false/true but will always be returned as 0/1 (0=false, 1=true).

place
Describes a loading or unloading place.

Properties
Property Type Description
id integer Location ID in 123cargo database
lat float Latitude of location
lng float Longitude of location
name string Local name (Ex. Paris, London,
Vienna, Bucureşti)
country string 2 letter country ISO-3166 code
postalCode string

In case the place is required to be a city, in order to properly identify the city the following
properties are used in this order:

1. If id is present then we only use that and update the rest of the fields.
2. If name and country are present we use those and return the first result. Id, lat, lng are
updated.
3. If lat and lng are valid coordinates then we return the closest city to that point also
filtering by country if it’s set.

In case the place does not need to be a city only country is mandatory.

truckType
List of possible type of trucks. Only truck types within the same group can be combined in arrays like
load->requiredTruck[].

truckType Description Group

1 Box A
2 Tilt A
3 Flat A
9 Oversized A
10 Car transporter A
5 Tipper A
6 Tank B
8 Liquid food container B
7 Container C
companyScoring
Provides information about company scoring.

Scores are numeric values from 0 to 4 representing the number of stars shown in 123cargo.

Trends are numeric values from -2 to +2 representing the score trend in the last 3 month:

- -2 rapid decrease
- -1 decrease
- 0 stagnant
- +1 increase
- +2 rapid increase

Properties
Property Type Description
score1 integer Forwarder score
trend1 integer Forwarder trend
score2 integer Carrier score
trend2 integer Carrier trend
score3 integer Customer score. Can be null in
case it does not apply
trend3 integer Customer trend
score4 integer Supplier score. Can be null in case
it does not apply

More information about scoring in 123cargo:

http://www.123cargo.eu/account/default/profilehelp/view/scoring

companyStatistics
Provides statistical information about a company.

Properties
Property Type Description
registrationDate date dd-mm-yyyy
foundingYear year yyyy
publishedLoads integer Total number of published loads
publishedTrucks integer Total number of published trucks
expiredLoads integer Number of loads marked as expired and
automatically deleted
expiredTrucks integer Number of trucks marked as expired and
automatically deleted
activePaymentDelays integer Number of active payment incidents with less
than 60 days past due date
solvedPaymentDelays integer Number of solved payment incidents with less
than 60 days past due date
activePaymentIncidents integer Number of active payment incidents with
more than 60 days past due date
solvedPaymentIncidents integer Number of solved payment incidents with
more than 60 days past due date
activeTransportIncidents integer Number of active transport incidents

company
Describes information about a company

Properties
Property Type Description
id integer Company id
name string Company name
country string 2 letter country ISO-3166 code
vatNumber string
sites[] site
scoring companyScoring Company scoring
revocations[] string List of company revocations
statistics companyStatistics Company statistics

companySearch
Formulates a company search.

Searches return a maximum of 50 results. If you need more results use offset to skip the first ones.

All properties work as wildcards if they are missing or set to null.

At least one search criteria must be present besides the mandatory country.

Properties
Property Type Description POST/PUT
name string Company name N
country string 2 letter country ISO-3166 Y
code
vatNumber string N

site
Provides information about a company site or office.

Properties
Property Type Description
id integer Site id
name string Site name
type string Site type (office, warehouse etc.)
address string
city string
postalCode string
country string 2 letter country ISO-3166 code
phones[] phone
emails[] string
contacts[] contact

contact
Provides information about a contact person

Properties
Property Type Description
id integer Contact id
name string Contact name
phones[] phone
emails[] string
languages[] string 2-5 letter language ISO 639-1 code
skype string Skype screenname

companyContact
Describes contact information of an entry. It is the same as company object but only populated with
valid information related to the entry (one site and one contact).

Price
Describes pricing information.

For loads price refers to full offered price of the transport, for trucks it represents the price/km
requested for transporting a load with that truck.

Properties
Property Type Description
price float
currency string 3 letter ISO- currency code
(RON, EUR, USD)
vat boolean if VAT is included

load
Describes a load.

Properties
Property Type Description POST/PUT
id string Load ID (BM-xxxxxx) -
externalReference integer Load ID in own system N
source place City
destination place City
loadingDate date Y
loadingInterval integer Number of days of availability Y
starting from loadingDate
requiredTruck[] truckType Y
weight float Kg Y
volume float m3 N
length float m N
hazardous boolean N
temperatureControlled boolean N
vehicles integer Number of vehicles for car N
transporter
container integer 20 or 40 for container type truck N
groupage boolean Request groupage N
description string Load description N
privateNotice string Private load description, only visible N
by the company that posted the
load
offeredPrice price N
contactInformation companyContact Read-only -

loadSearch
Formulates a search.

Searches return a maximum of 50 results. If you need more results use offset to skip the first ones.

All properties work as wildcards if they are missing or set to null.

Example: if hazardous is unset or null the search returns all loads; if hazardous is true then
search returns only those loads that have the hazardous property set to true; if false then it will
return all loads with hazardous set to false.

One of source or destination must be set to either a city or a country.

The property weightMax is only valid if groupage is set to true and in this case weight property
represents the minimum weight accepted.

Use global GET parameters limit and offset to control which results are returned.

Properties
Property Type Description POST
source place N
destination place N
internationalOnly boolean Only international loads N
extendedRange integer Search range from 0 to 2 N
loadingDate date Y
loadingInterval integer Number of days of availability Y
starting from loadingDate
requiredTruck[] truckType N
weight float Kg N
weightMax float Kg, only valid with N
 groupage=true
volume float m3 N
length float m N
hazardous boolean N
temperatureControlled boolean N
vehicles integer Number of vehicles for car N
transporter
container integer 20 or 40 for container type N
truck
groupage boolean Requested groupage N

truck
Describes a truck

Property Type Description POST/PUT

id string Truck ID (BC-xxxxxx) -
source place City
destinations place[] List of possible destinations Y
(city or country). Maximum 5.
availableDate date The date the truck is available Y
for loading
availableInterval integer Number of days of availability Y
starting from availableDate
truckType truckType Y
weight float Kg Y
volume float m3 N
length float m N
hazardous boolean N
temperatureControlled boolean N
vechicles integer N
container integer 20 or 40 for container type N
truck
groupage boolean If the truck is empty or Y
partially loaded
description string N
privateNotice string Private truck description, only N
visible by the company that
posted the truck
requestedPrice price N
contactInformation companyContact Read-only -

truckSearch
Formulates a search.

Searches return a maximum of 50 results. If you need more results use offset to skip the first ones.

All properties work as wildcards if they are missing or set to null.

Example: if hazardous is unset or null the search returns all trucks; if hazardous is true then
search returns only those trucks that have the hazardous property set to true; if false then it will
return all trucks with hazardous set to false.

One of source or destination must be set to either a city or a country.

Use global GET parameters limit and offset to control which results are returned.

Properties
Property Type Description POST
source place N
destination place N
extendedRange integer Search range from 0 to 2 N
availableDate date Y
availableInterval integer Number of days of availability Y
starting from loadingDate
truckType[] truckType N
weight float Kg N
volume float m3 N
length float m N
hazardous boolean N
temperatureControlled boolean N
vehicles integer Number of vehicles for car N
transporter
container integer 20 or 40 for container type N
truck
groupage boolean Requested groupage N
Request URIs
PUT/POST/GET requirements signification:

Symbol Meaning
- Ignored
Y Mandatory field
City Mandatory city level for objects of type place
N Optional field
/loads
Methods summary
Method Description HTTP request
GET Returns a list of own loads GET /loads
POST Creates a load POST /loads
PUT Updates a load PUT /loads/<ID>
DELETE Deletes a load or a list of loads DELETE /loads/<ID>

GET
Returns a list of own loads in an array with load type elements indexed by the load.id property.

Use global GET parameters limit and offset to control which results are returned.

POST
Adds a new load.

Request body must contain the JSON encoded load object.

Response will contain the load object or the validation errors in case of error.

PUT
Updates an existing load.

<ID> parameter must be in BM-xxxxxx format. Request body must contain the JSON encoded load
object.

Response will contain the load object or the validation errors in case of error.

DELETE
Deletes an existing load.

<ID> parameter must be in BM-xxxxxx format.

/searchloads
Methods summary
Method Description HTTP request
POST Search for loads POST /searchloads

POST
Searches for loads.

Request body must contain the JSON encoded loadSearch object.

Returns a list of loads found in an array with load type elements indexed by the load.id property.
/trucks
Methods summary
Method Description HTTP request
GET Returns a list of own trucks GET /trucks
POST Creates a truck POST /trucks
PUT Updates a truck PUT /trucks/<ID>
DELETE Deletes a truck or a list of trucks DELETE /trucks/<ID>

GET
Returns a list of own loads in an array with truck type elements indexed by the truck.id property.

Use global GET parameters limit and offset to control which results are returned.

POST
Adds a new truck.

Request body must contain the JSON encoded truck object.

Response will contain the truck object or the validation errors in case of error.

PUT
Updates an existing truck.

<ID> parameter must be in BC-xxxxxx format. Request body must contain the JSON encoded truck
object.

Response will contain the truck object or the validation errors in case of error.

DELETE
Deletes an existing truck.

<ID> parameter must be in BC-xxxxxx format.

/searchtrucks
Methods summary
Method Description HTTP request
POST Search for trucks POST /searchtrucks

POST
Searches for trucks.

Request body must contain the JSON encoded truckSearch object.

Returns a list of trucks found in an array with truck type elements indexed by the truck.id property.
/companies
Methods summary
Method Description HTTP request
GET Returns own company information GET /companies
GET Returns information about a company GET /companies/<ID>
POST Searches for a company POST /companies

GET
Get returns a company type element populated with all sites and contacts.

POST
Search for companies.

Request body must contain the JSON encoded companySearch object.

Returns a list of companies found in an array with company type elements indexed by company.id
property.

/places
Searches for a place the same way it is being searched on posting.

Methods summary
Method Description HTTP request
POST Searches for a place POST /places

POST
Request body must contain the JSON encoded place object.
Responses
All API calls return the following response with a HTTP status code:

Property Type
resultCode integer resultCode Description
response string | 0 Ok
object[] 1
availableResults
Error
integer

HTTP Status Code Description

200 OK
400 Bad Request (invalid input parameters)
401 Unauthorized (invalid or missing HTTP basic authentication)
402 Payment Required (user does not have access to the API)
403 Forbidden (user does not have access to the specified operation)
404 Not Found
500 Internal Server Error
Change log
0.55 – 19.08.2015
- replace brand name

0.54 – 13.11.2014
- add skype id to contacts
- add company statistics

0.53 – 10.11.2014
- add scoring information for companies
- add revocation information for companies
- basic company search

0.52 – 23.10.2014
- add externalReference for loads

0.51 – 07.06.2014
- add postalCode to Site and remove redundant information from addrees property

0.5 – 16.04.2014
- add availableResults to API call return for searches and own loads and trucks
- add explanation for boolean values
- add offset and limit global pagination parameters that apply to searches and own
information
- remove offset from loadSearch and truckSearch, now using global offset and limit