Overview

SERVICE DESCRIPTION

This service provides integration with the Mapbox platform through the GHUBEE interface. It enables interactive map rendering with multiple points, custom marker visualization, route display, and geocoding search capabilities for location-based services.

INTEGRATION SPECIFICATION
Service Details

Service Name	Mapbox Map, Mapbox Pointers, Mapbox Geocoding
Context	/mapbox /mapboxPointers/data-load /mapbox/geocoding
Description	Provides endpoints to render interactive maps with multiple coordinates, display custom markers with GeoJSON features, and perform geocoding operations to search addresses and locations using Mapbox services.
Endpoint	https://hml.ghubee.com/api/mapbox https://hml.ghubee.com/api/mapboxPointers/data-load https://hml.ghubee.com/api/mapbox/geocoding
Environment Specifications	https://ghubee.com/api
Protocol/Transport	HTTPS
Method	POST / GET
Representation format	JSON / HTML
Input/Output Interface or Both	Both
Data transformation	No

Assumption

The service must be invoked with all mandatory parameters correctly filled.

Authentication is required to access Mapbox services through GHUBEE using Bearer token.

Mapbox access token is configured internally and managed by GHUBEE system.

Data input

Identification of the input data for the Mapbox APIs.

Field	Description	Format	Required	Remarks
Token_Ghubee	Authentication token	Authorization Header	Yes	Bearer token
Mapbox Map Endpoint (/api/mapbox)
long	Array of longitude coordinates	JSON Array	Yes	Must match long array length
lat	Array of latitude coordinates	JSON Array	Yes	Must match long array length
Mapbox Pointers Endpoint (/api/mapboxPointers/data-load)
pointers	GeoJSON Feature array	JSON Array	Yes	Array of Feature objects
pointers[].type	Feature type	String	Yes	Must be "Feature"
pointers[].geometry	Geometry object	JSON Object	Yes	Point geometry
pointers[].geometry.type	Geometry type	String	Yes	Must be "Point"
pointers[].geometry.coordinates	Point coordinates	Array	Yes	[longitude, latitude]
pointers[].properties	Feature properties	JSON Object	Yes	Metadata for the point
pointers[].properties.title	Point title	String	No	Display name
pointers[].properties.description	Point description	String	No	Additional information
custom_marker	Custom marker image URL	String (URL)	No	Optional marker icon
Mapbox Geocoding Endpoint (/api/mapbox/geocoding)
searchText	Address or location search query	Query Parameter	Yes	URL-encoded address string

Data input example

Mapbox Map:

POST https://hml.ghubee.com/api/mapbox
Authorization: Bearer token_ghubee
Content-Type: application/json
{  
  "long": [  
    -46.6333,  
    -46.6555,  
    -46.6777,  
    -46.7000  
  ],  
  "lat": [  
    -23.5505,  
    -23.5615,  
    -23.5725,  
    -23.5835  
  ]  
  }

Mapbox Pointers:

POST https://hml.ghubee.com/api/mapboxPointers/data-load
Authorization: Bearer token_ghubee
Content-Type: application/json
{  
  "pointers": \[  
    {  
      "type": "Feature",  
      "geometry": {  
        "type": "Point",  
        "coordinates": [-46.6333, -23.5505]  
      },  
      "properties": {  
        "title": "MASP",  
        "description": "Museu de Arte de São Paulo"  
      }  
    },  
    {  
      "type": "Feature",  
      "geometry": {  
        "type": "Point",  
        "coordinates": [-46.6555, -23.5615]  
      },  
      "properties": {  
        "title": "Parque Ibirapuera",  
        "description": "Principal parque da cidade"  
      }  
    }  
  ],  
  "custom_marker": ""  
    }

Mapbox Geocoding:

GET https://hml.ghubee.com/api/mapbox/geocoding?searchText=1440%20Monroe%20St%2C%20Madison%2C%20WI%2053711
Authorization: Bearer token_ghubee
Accept: application/json

Data output

Return of Mapbox API output data.

Field	Description	Format	Required	Remarks
Mapbox Map & Pointers Output
HTML Response	Rendered interactive map	HTML	Yes	Map with markers/points
Mapbox Geocoding Output
status	Response status	String	Yes	Success / Error
message	Response message	String	Yes	Status description
data	Geocoding results container	Object	Yes	GeoJSON FeatureCollection
data.type	Collection type	String	Yes	Always "FeatureCollection"
data.query	Parsed search query	Array	Yes	Tokenized search terms
data.features	Array of location results	Array	Yes	Matching locations
features[].id	Unique feature identifier	String	Yes	Mapbox feature ID
features[].type	Feature type	String	Yes	Always "Feature"
features[].place_type	Location type	Array	Yes	address, place, postcode, etc.
features[].relevance	Search relevance score	Decimal	Yes	0.0 to 1.0
features[].properties	Feature metadata	Object	Yes	Mapbox ID, accuracy, etc.
features[].text	Primary location name	String	Yes	Street name or place name
features[].place_name	Full formatted address	String	Yes	Complete address string
features[].center	Geographic center coordinates	Array	Yes	[longitude, latitude]
features[].geometry	GeoJSON geometry	Object	Yes	Point geometry data
features[].geometry.type	Geometry type	String	Yes	Always "Point"
features[].geometry.coordinates	Point coordinates	Array	Yes	[longitude, latitude]
features[].address	Street address number	String	Conditional	If place_type is "address"
features[].context	Hierarchical context	Array	Yes	Postcode, place, region, country
features[].bbox	Bounding box coordinates	Array	Conditional	[minLon, minLat, maxLon, maxLat]
data.attribution	Mapbox attribution notice	String	Yes	Copyright and terms of service

Error messages

Identification and description of error message types.

Situation	Message Code	Message description
Unauthenticated	{ "erro": true, "msg": "Unauthenticated" }	Authentication error with GHUBEE. Bearer token missing or invalid.
Unauthorized	{ "erro": true, "msg": "Unauthorized" }	User does not have permission to access this service.
No coordinates found	{ "erro": true, "msg": "No coordinates found." }	Required latitude/longitude arrays missing or not in array format.
Coordinate mismatch	{ "erro": true, "msg": "Enter an equal number of latitudes and longitudes." }	Array length mismatch between lat and long parameters.
Insufficient balance	{ "message": "Insufficient balance to consume the API, please access your account and add credit." }	Account balance insufficient to make API calls.
Mapbox API Error	{ "status": "Error", "message": "cURL error: [error details]" }	Communication error with Mapbox API.
Geocoding Error	{ "status": "Error", "message": "[error message]" }	Error during geocoding operation or invalid search text.