Home B2Core IB API Location services

Location services

On this page:

THE LOCATION SERVICE OBJECT	A detailed description of the JSON object
THE LOCATION SERVICE DRIVER OBJECT	A detailed description of the JSON object
GET[base]/location	Get a list of location services
GET[base]/location/{serviceId}	Get location service details
POST[base]/location	Add a new location service
PUT[base]/location/{serviceId}	Update a location service
DELETE[base]/location/{serviceId}	Delete a location service
GET[base]/location/{serviceId}/drivers	Get a list of location service drivers
GET[base]/location/{serviceId}/drivers/{driverId}	Get location service driver details
PUT[base]/location/{serviceId}/drivers/{driverId}	Update a location service driver
GET[base]/location/{serviceId}/drivers/{driverId}/diagnostics	Run location service diagnostics
GET[base]/location/{serviceId}/updates	Check for updates

The Location service object

This object provides the following data about a location service:

serviceId string

The location service identifier.

name string

The location service name.

priority integer

The location service priority.

provider string

The location service provider.

database object

The information about the location service database.

Expand fields

version string: The database version.
records integer: The number of records in the database.
size integer: The database size.
updateTime string: The date and time when the object has been last updated.

createTime string

The date and time when the object has been created.

updateTime string

The date and time when the object has been last updated.

uuid string

The universally unique identifier of the object (if provided). Refer to Integrations for more information.

    THE LOCATION SERVICE OBJECT
  
{
  "serviceId": "6006dda272f002519c3eb505",
  "name": "MaxMind",
  "priority": 1,
  "provider": "maxmind",
  "database": {
    "version": "2.0",
    "records": 5107510,
    "size": 5107510,
    "updateTime": "2021-01-01T00:00:00+00:00"
  },
  "createTime": "2021-01-01T00:00:00+00:00",
  "updateTime": "2021-01-01T00:00:00+00:00",
  "uuid": null
}

The Location driver object

This object provides the following data about a location driver:

driverId string: The driver identifier.
driverNumber string: The driver number.
address string: The driver address.
name string: The driver name.
provider string: The driver provider.
version integer: The version of a driver.
createTime string: The date and time when the object has been created.
updateTime string: The date and time when the object has been last updated.
uuid string: The unique universal identifier of the object (if provided). Refer to Integrations for more information.

    THE LOCATION SERVICE DRIVER OBJECT
  
{
  "driverId": "6006dda272f002519c3eb505",
  "driverNumber": "12345",
  "address": "https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-City&suffix=tar.gz",
  "name": "MaxMind",
  "provider": "API",
  "version": 2,
  "createTime": "2021-01-01T00:00:00+00:00",
  "updateTime": "2021-01-01T00:00:00+00:00",
  "uuid": null
}

Get a list of location services

Use this method to obtain a list of configured location services.

To obtain detailed information about a specified location service, use a separate method to get location service details.

Request

Header parameters:

Authorization: Bearer <token>

Query parameters:

This method supports pagination and sorting. For details on applying the parameters, refer to the Query parameters section. Possible parameters for sorting are listed below. For values description, refer to the Location service object.

Possible values for the sort_by parameter:

name
createTime (default)
priority
provider
updateTime

GET[base]/location

curl --location --request GET 'https://your.base-url.here/location?limit=10&offset=0&sort_by=createTime&sort_order=desc' \
--header 'Authorization: Bearer <token>'

Response

Body:

In case of success, the response body contains an array of Location service objects providing information about all location services that correspond to the query parameters specified in the request.

Get location service details

Use this method to obtain detailed information about a specified location service.

To obtain a list of location services, use a separate method to get a list of location services.

Request

Header parameters:

Authorization: Bearer <token>

Path parameters:

serviceId required: The location service identifier.

GET[base]/location/{serviceId}

curl --location --request GET 'https://your.base-url.here/location/60ba407d15951453e60e49f8' \
--header 'Authorization: Bearer <token>'

Response

Body:

In case of success, the response body contains a Location service object providing information about the specified location service.

Add a new location service

Use this method to add a new location service.

Request

Header parameters:

Authorization: Bearer <token>
Content-Type: application/json

Body:

provider string required

The identifier location service provider.

drivers array

An array of Drivers objects.

Expand fields

address string

The address of a driver.

The string value length can’t exceed 1024 characters.

name string

The name of a driver.

The string value length can’t exceed 255 characters.

provider string

The driver provider.

version integer

The version of a driver.

credentials object

The credentials used to access a driver.

priority integer

The priority of the location service.

name string

The location service name.

The string value length can’t exceed 1024 characters.

uuid string

The unique universal identifier of the object (if provided). Refer to Integrations for more information.

The string value length can’t exceed 255 characters.

POST[base]v1/location

curl --location --request POST 'https://your.base-url.here/location' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
  "provider": "maxmind",
  "drivers": [
    {
      "address": "https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-City&suffix=tar.gz",
      "name": "MaxMind",
      "provider": "API",
      "version": 2,
      "credentials": {
        "key": "credentials"
      }
    },
    {
      "address": "https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-City&suffix=tar.gz",
      "name": "MaxMind",
      "provider": "API",
      "version": 2,
      "credentials": {
        "key": "credentials"
      }
    }
  ],
  "priority": 1,
  "name": "MaxMind",
  "uuid": null
}'

Response

Body:

In case of success, the response body contains a Location service object providing information about the newly added location service.

Update a location service

Use this method to update a specified location service.

Note

Instead of the method described below, you can use a similar method that uses the HTTP verb PATCH.

Request

Header parameters:

Authorization: Bearer <token>
Content-Type: application/json

Path parameters:

serviceId required: The location service identifier.

Body:

Values of the following fields can be updated:

priority integer

The priority of the location service.

name string

The location service name.

The string value length can’t exceed 1024 characters.

uuid string

The unique universal identifier of the object (if provided). Refer to Integrations for more information.

The string value length can’t exceed 255 characters.

PUT[base]/location/{serviceId}

curl --location --request PUT 'https://your.base-url.here/location/60ba407d15951453e60e49f8' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
  "priority": 1,
  "name": "MaxMind",
  "uuid": null
}'

Response

Body:

In case of success, the response body contains a Location service object providing information about the updated location service.

Delete a location service

Use this method to delete a location service.

Request

Header parameters:

Authorization: Bearer <token>

Path parameters:

serviceId required: The location service identifier.

DELETE[base]/location/{serviceId}

curl --location --request DELETE 'https://your.base-url.here/location/60ba407d15951453e60e49f8' \
--header 'Authorization: Bearer <token>'

Response

Body:

In case of success, no response body is returned.

Get a list of location service drivers

Use this method to obtain a list of location service drivers.

To obtain detailed information about a specified location service driver, use a separate method to get location service driver details.

Request

Header parameters:

Authorization: Bearer <token>

Path parameters:

serviceId required: The location service identifier.

GET[base]/location/{serviceId}/drivers

curl --location --request GET 'https://your.base-url.here/location/60ba407d15951453e60e49f8/drivers' \
--header 'Authorization: Bearer <token>'

Response

Body:

In case of success, the response body contains an array of Driver objects providing information about all drivers that correspond to the query parameters specified in the request.

Get location service driver details

Use this method to obtain detailed information about a specified location service driver.

To obtain a list of location service drivers, use a separate method to get a list of location service drivers.

Request

Header parameters:

Authorization: Bearer <token>

Path parameters:

serviceId required: The location service identifier.
driverId required: The driver identifier.

GET[base]v1/location/{serviceId}/drivers/{driverId}

curl --location --request GET 'https://your.base-url.here/location/60ba407d15951453e60e49f8/drivers/60ba407d15951453e60e49f8' \
--header 'Authorization: Bearer <token>'

Response

Body:

In case of success, the response body contains a Driver object providing information about the driver.

Update a location service driver

Use this method to update a specified location service driver.

Note

Instead of the method described below, you can use a similar method that uses the HTTP verb PATCH.

Request

Header parameters:

Authorization: Bearer <token>
Content-Type: application/json

Path parameters:

serviceId required: The location service identifier.
driverId required: The driver identifier.

Body:

Values of the following fields can be updated:

address string

The address of a driver.

The string value length can’t exceed 1024 characters.

name string

The name of a driver.

The string value length can’t exceed 255 characters.

version integer

The version of a driver.

credentials object

The credentials used to access a driver.

PUT[base]/location/{serviceId}/drivers/{driverId}

curl --location --request PUT 'https://your.base-url.here/location/60ba407d15951453e60e49f8/drivers/60ba407d15951453e60e49f8' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
  "address": "https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-City&suffix=tar.gz",
  "credentials": {
    "key": "credentials"
  },
  "name": "MaxMind",
  "version": 2,
  "uuid": null
}'

Response

Body:

In case of success, the response body contains a Driver object providing information about the updated driver.

Run location service diagnostics

Use this method to run the location service diagnostics.

Request

Header parameters:

Authorization: Bearer <token>

Path parameters:

serviceId required: The location service identifier.
driverId required: The driver service identifier.

GET[base]/location/{serviceId}/drivers/{driverId}/diagnostics

curl --location --request GET 'https://your.base-url.here/location/60ba407d15951453e60e49f8/drivers/60ba407d15951453e60e49f8/diagnostics' \
--header 'Authorization: Bearer <token>'

Response

Body:

health boolean: If true, the connection to a location service is alive. If false, diagnostics failed.
message string: If diagnostics failed, this field contains a problem description. If the connection to a location service is alive, null.

    RESPONSE BODY EXAMPLE
  
{
  "health": true,
  "message": null
}

Check for updates

Use this method to check for available updates for the location service database.

Request

Header parameters:

Authorization: Bearer <token>

Path parameters:

serviceId required: The location service identifier.

GET[base]/location/{serviceId}/updates

curl --location --request GET 'https://your.base-url.here/location/60ba407d15951453e60e49f8/updates' \
--header 'Authorization: Bearer <token>'

Response

Body:

database object

The information about the location service database.

Expand fields

version string: The database version.
records integer: The number of records in the database.
size integer: The database size.
updateTime string: The date and time when the object has been last updated.

health boolean

If true, the connection to a location service is alive. If false, diagnostics failed.

message string

If diagnostics failed, this field contains a problem description. If the connection to a location service is alive, null.

    RESPONSE BODY EXAMPLE
  
{
  "database": {
    "version": "2.0",
    "records": 5107510,
    "size": 5107510,
    "updateTime": "2021-01-01T00:00:00+00:00"
  },
  "health": true,
  "message": null
}