The following describes the construct of API URL, its query parameters, needed headers and response structure.

API URL Construction

Context API has several components to make up the URL used for the REST call which includes:

  • Base URL
  • Endpoint (which includes the API Current Version)
  • Resource
  • Parameters

<base_url>/mcs/<api_version>/<resource> (i.e context.micello.com/mcs/v0/lc )

The current api_version is “v0”. 

Base URL: 

https://context.micello.com

Resource: 

mcs

Required query parameters

 "lat": latitude, North/South geolocation component - Value range: ‐90.0 to 90.0 [Data type double],
 "lon": longitude, East/West geolocation component - Value range: ‐180.0 to 180.0 [Data type double],
 "key": Your valid API key from Micello.com

Optional Parameters

 "radius": distance from the given lat & lon, limiting the search area - Value range: 0 to 1000 [Unit is meters],
 "ep": Boolean value (Control entity prop display in output). Default value is set to true. ,
 "geometry_type": limits search result to specified geometry_type, allowed set of values is specified in Appendix A.2 

Protocol : 

GET

Sample URL 

https://context.micello.com/mcs/v0/lc?lon=-121.9284&lat=37.695&key=your_api_key

Response JSON:

{        
    "api_version": version,
    "release_version": release_version,
    "success": boolean value indicating if the request was completed successfully,                        
    "message": text describing the cause of request failure [optional],
    "type": static text "FeatureCollection", defining type of GeoJSON object,
    "feature": array of feature object that contains the contextual information ( its structure is defined below ), 
    "venue_prop": array of 'community property' object of micello venue that contains the specifed lat,lon. 
}

JSON structure of feature object 

{
    "m_object_type": Defines the object type whose information is contained in this JSON.
    "id": Micello identifier corresponding to value contained by m_object_type [Data type Long],
    "distance": distance in meter between centroid of this object and the lat,lon specified in request [Data type Float]
    "geometry_prop": {                // JSON object containing geometry properties
        "properties " {},             // Language independent geometry properties   
        "properties: < lang > " {},   // the value JSON contains language specific properties
    },
    "entity_prop": [                  // JSON array containing properties of entity associated to the geometry.
        {
            "properties ": {},          // Language independent entity properties
            "properties: < lang > " {}, // the value JSON contains language specific properties
        }, …
    ],
    "m_object_venue_prop": {
        "lid": level-id ,      // not null if m_object_type=’geometry’/’level’/’level_indoor’
        "did": drawing-id ,    // null if m_object_type=’community’/’community_indoor’
        "cid": community-id
    },
    "type": static text "Feature", defining type of GeoJSON object,
}

Note

  • Community property object is defined in the com_map section of  Micello GeoJSON Spec.
  • m_object_type value is from the set {geometry, level, level_indoor, drawing, drawing_indoor, community, community_indoor}.
  • key-value pair distance is available only in case the valid radius parameter is specified in URL.
  • If query parameter “radius” is not provided, API will return details of the objects that the given point contains.
  • Geometry properties key-values are derived from Micello metadata.
  • key-value associated with geometry_prop & entity_prop is available only if m_object_type is geometry.
  • Entity properties key-values are derived from Micello metadata.
  • <lang> is the short code for language ex "en" for english, "ja" for japenese, for detail list refer Micello metadata.

HTTP Response status

           Refer Appendix  - A.1 

Appendix

A.1) HTTP response status codes

Code Description
200 Success
400 Invalid query parameters
401 Not authorized
500 Internal server error
403 Forbidden : Invalid resource request

A.2) Valid Geometry Types

check-in copy-print greenery movie theater shelf
airplane crosswalk ground intersect moving walkway shoe shine
aisle customer service ground transportation obstruction showers
area customs guide office smoke
atm defibrillator gym opening stage
wall desk hall area parcel stairs
auditorium door hallway parking lot stairwell
baggage claim doorway immigration and customs passport control step
bathroom earth inaccessible space patio stop sign
bike rack elevator information pet relief area stroller
bin emergency exit kiosk playground subbuilding
booth entrance lab police-security table
building escalator level outline power taxi
building background eyewash library railway telephone
bus fire extinguisher lobby railway rail tent
cafeteria fire hose locker railway tie ticketing
car rental fire pull locker room ramp traffic light
cash register first aid lost and found rest area traffic marker
chair fitness center luggage cart restaurant train
changing station flight monitor mail road transit hotel
checkout floor opening massage chair room tree
classroom food and drink medical santa tv
cocktails garden meditation room seat unit
coffee gate meeting point section vending machine
conference room grass money changer security section walkway
water wifi window yield sign  

Note: some of the geometry_type are specific to map type, for details refer the presets file, the URL to access presets file is

https://mfs.micello.com/ms/v1/mfile/meta/presets/v5/Standard?key=<your_api_key>