Position-lab

Content

API Documentation

On this page, you will find all the information about the integration and usage of Position-lab APIs. Before you start anything, you will need an API key, which you can obtain by choosing one of our pricing plans. If you have any questions after reading the documentation, please do not hesitate to contact us.

Geocoding API

Overview

Position-lab API offers developers an accurate and robust geocoding solution, allowing both forward and reverse geocoding functionalities, as well as landmark geocoding.

API Request

1. Forward Geocoding

Retrieve geographic coordinates by inputting a structured or free-form address.

Example:

Trafalgar Square, Westminster London, WC2N 5DN, United Kingdom →
lat: 51.5080° N; long: -0.1281° W
 

Endpoint:

GET /forwardGeocode

Parameters:
  • address: The address to be converted to coordinates.

 

Example Request:

				
					https://api.position-lab.com/reverseGeocode?lat=51.5080&lon=-0.1281

				
			

2. Reverse Geocoding API

Convert geographical coordinates to a human-readable address or place name.

Example:

lat: 51.5080° N; long: -0.1281° W →
Trafalgar Square, Westminster London, WC2N 5DN, United Kingdom
 

Endpoint:

GET /reverseGeocode

Parameters:
  • lat: Latitude of the location.
  • lon: Longitude of the location.

 

Example Request

				
					https://api.position-lab.com/reverseGeocode?lat=51.5080&lon=-0.1281

				
			

3. Landmark Geocoding API

Retrieve coordinates of notable landmarks.

Example:

Eiffel Tower, Paris, France →
lat: 48.8588443° N; long: 2.2943506° E

Endpoint:

GET /landmarkGeocode

Parameters:
  • landmark: Name of the landmark.

Example Request:

				
					https://api.position-lab.com/landmarkGeocode?landmark=Eiffel+Tower,+Paris,+France&api_key=API_KEY
				
			

API Response

Every API endpoint returns a structured JSON response containing comprehensive location information to fulfill various geocoding requirements. Below is a detailed explanation of the response structure:

locationDetails (Array)

An array of objects, each providing detailed information about a specific location or landmark. The properties within each object include:

Basic Location Properties
  • lat (float): Latitude of the location.
  • lon (float): Longitude of the location.
  • addressName (string): A recognizable name or title of the location.
  • category (string): The type or category of the location, such as ‘location’, ‘landmark’, etc.
  • buildingNo (string): The building number in the address.
  • streetName (string): The name of the street in the address.
  • zipCode (string): Postal code of the location.
  • accuracy (float): A confidence score (between 0 and 1) indicating the precision of the geocoding result.
  • city (string): The city where the location is situated.
  • stateCode (string): The state or province code.
  • district (string | null): The district or neighborhood, if applicable.
  • area (string): A general area or locality information.
  • nation (string): The country name.
  • isoCode (string): The ISO country code.
  • formattedAddress (string): A human-readable address string.
  • mapLink (string): A URL for viewing the location on a map.
Country-Specific Details
  • countryDetails: An object containing detailed information about the country.
    • lat & lon (string): Generalized latitude and longitude of the country.
    • shortName & fullName (string): Short and full forms of the country’s name.
    • capitalCity (string): The capital city of the country.
    • flagIcon (string): URL to the country’s flag icon.
    • totalArea (number): The total area of the country in square kilometers.
    • isLandlocked (boolean): Indicates whether the country is landlocked.
    • isSovereign (boolean): Sovereign status of the country.
    • Additional fields regarding global info, phone details, currency, and spoken languages.
Sunlight Information
  • sunlightInfo: An object containing details about sunlight times.
    • sunrise & sunset: Objects containing various times of sunrise and sunset.
      • exactTime, astroTime, civilTime (number): Different timestamp variants.
    • highestPoint (number): Timestamp of the sun reaching its highest point.
Time-Related Information
  • timeDetails: An object with time zone information.
    • zoneName (string): The time zone name.
    • timeDifference (number): Time difference from UTC in hours.
    • diffString (string): Time difference in HH:mm format.

Response example

				
					{
    "locationDetails": [
        {
            "lat": 51.5074,
            "lon": -0.1278,
            "addressName": "10 Downing St",
            "category": "location",
            "buildingNo": "10",
            "streetName": "Downing St",
            "zipCode": "SW1A 2AA",
            "accuracy": 0.9,
            "city": "London",
            "stateCode": "LND",
            "district": null,
            "area": "Westminster",
            "nation": "United Kingdom",
            "isoCode": "GB",
            "formattedAddress": "10 Downing St, Westminster, London, LND, UK",
            "mapLink": "https://map.example.com/?lat=51.5074&lon=-0.1278",
            "countryDetails": {
                "lat": "54.3781",
                "lon": "-3.4360",
                "shortName": "UK",
                "fullName": "United Kingdom of Great Britain and Northern Ireland",
                "capitalCity": "London",
                "flagIcon": "",
                "totalArea": 242495,
                "isLandlocked": false,
                "isSovereign": true,
                "globalInfo": {
                    "twoCharCode": "GB",
                    "threeCharCode": "GBR",
                    "numericID": "826",
                    "continent": "Europe",
                    "subRegion": "Northern Europe",
                    "continentCode": "EU",
                    "subRegionCode": "154",
                    "worldArea": "EUR",
                    "continentFullName": "Europe",
                    "continentID": "EU"
                },
                "phoneDetails": {
                    "dialCode": "44",
                    "domesticPrefix": "0",
                    "internationalPrefix": "00"
                },
                "currency": [
                    {
                        "icon": "£",
                        "currencyCode": "GBP",
                        "currencyName": "Pound Sterling",
                        "currencyID": 826,
                        "fractionalUnit": 2
                    }
                ],
                "spokenLanguages": {
                    "eng": "English"
                }
            },
            "sunlightInfo": {
                "sunrise": {
                    "exactTime": 1575733924,
                    "astroTime": 1575728051,
                    "civilTime": 1575732092
                },
                "sunset": {
                    "exactTime": 1575767704,
                    "astroTime": 1575773576,
                    "civilTime": 1575769535
                },
                "highestPoint": 1575750814
            },
            "timeDetails": {
                "zoneName": "Europe/London",
                "timeDifference": 0,
                "diffString": "+00:00"
            }
        }
    ]
}
				
			

Geosearch API

Overview

The Geosearch API enhances user experience in map applications by providing dynamic and intelligent location suggestions, auto-completing user input in real-time with precise locations from a vast global database. By recognizing addresses and landmarks with just partial user input, it ensures a user-friendly and efficient search functionality, bridging user intent and accurate geographical data seamlessly.

 

API Request

Endpoint:

GET /geosearch

Parameters:
  • query: (String) The input string from the user’s search, which we want to find location suggestions for.
  • limit: (Integer, optional) The maximum number of suggestions to return.

Example Request:

 

				
					https://api.position-lab.com/geosearch?query=New+York&limit:100&api_key=API_KEY
				
			

API Response

  • suggestions: An array containing suggested location objects based on the input query.
  • name: The complete, human-readable name of the location.
  • type: A string that classifies the location (e.g., city, landmark, etc.).
  • latitude: A float representing the geographical latitude of the location.
  • longitude: A float representing the geographical longitude of the location.
  • region: A string that indicates the broader geographical or administrative area where the location is situated.

Response example

				
					{
  "suggestions": [
    {
      "name": "New York, NY, USA",
      "type": "city",
      "latitude": 40.7128,
      "longitude": -74.0060,
      "region": "United States"
    },
    {
      "name": "New York Mills, MN, USA",
      "type": "city",
      "latitude": 46.5180,
      "longitude": -95.3762,
      "region": "United States"
    }
  ]
}

				
			

Nearby Places API

Overview

Utilize the Nearby Places API to effortlessly locate and obtain detailed information about places within a defined proximity by inputting specific coordinates and radius. With customization options, filter your searches to pinpoint places based on streets, categories, or specific names, enabling your application to deliver precise and user-centric localized experiences.

 

API Request

Endpoint:

GET /nearby

Parameters:
  • 1. Location Parameters:
    • latitude (Required): The latitude of the focal point around which to retrieve nearby places.
    • longitude (Required): The longitude of the focal point around which to retrieve nearby places.
    • postal_code
    • street
    2. Search Parameters:
    • query (Optional): A search query string to find specific places or types of places (e.g., “cafe”, “museum”).
    • category (Optional): Allows the user to filter results by predefined categories (e.g., “restaurant”, “hospital”). The API should support multiple categories (e.g., “restaurant,cafe”).
    • open_now (Optional): Boolean parameter to only return places that are open at the time of the query.
    • dog_friendly (Optional): Boolean parameter to filter results for places that are dog-friendly.
    • free_parking
    • wheelchair_accessible
    3. Distance Parameters:
    • radius (Optional): Defines the distance (in meters) within which to return place results. The maximum allowable radius may be stipulated by the API.
    4. Pagination and Sorting:
    • limit (Optional): Maximum number of results to return in a single response (pagination).
    • offset (Optional): Number of results to skip from the beginning (for pagination).
    • sort_by (Optional): Parameter to sort results (e.g., “distance_asc”, “rating_desc”).
    5. Additional Filter Parameters:
    • price_range (Optional): Used to filter places within a certain price range (could be numerical or categorical, e.g., “$”, “$$-$$$”).
    • rating (Optional): Minimum rating to filter places (e.g., places with a rating of 4.5 and above).

     

Example Request:

				
					https://api.position-lab.com/nearby?
    latitude=40.748817&
    longitude=-73.985428&
    query=cafe&
    category=coffee_shop&
    open_now=true&
    dog_friendly=true&
    radius=1000&
    limit=10&
    offset=0&
    sort_by=rating_desc&
    price_range=$$&
    rating=4.0&
    output=json&
    api_key=YOUR_API_KEY
				
			

API Response

  • id: Unique identifier for the place.
  • name: Name of the place.
  • address: Physical address of the place.
  • latitude & longitude: Geographical coordinates of the place.
  • category: Type/category of the place.
  • tags: Array containing additional attributes of the place (e.g., “open_now”, “dog_friendly”).
  • rating: Numeric rating of the place.
  • opening_hours: Object providing opening hours for each day of the week.
  • contact: Contact number of the place.
  • website: URL of the place’s website.
  • total_results: The total number of results found by the API (without limit and offset applied).
  • limit: The maximum number of results returned in this response.
  • offset: The number of results skipped (if paginated).
  • radius: The search radius used in the API request.

Response example

				
					{
    "status": "success",
    "data": {
        "places": [
            {
                "id": "12345",
                "name": "Brew Buddy Cafe",
                "address": "123 4th Street, NY",
                "latitude": 40.731610,
                "longitude": -73.936250,
                "category": "cafe",
                "tags": ["open_now", "dog_friendly"],
                "rating": 4.5,
                "opening_hours": {
                    "monday": "8:00 AM - 9:00 PM",
                    "tuesday": "8:00 AM - 9:00 PM",
                    "wednesday": "8:00 AM - 9:00 PM",
                    ...
                },
                "contact": "+1 (234) 567-8901",
                "website": "http://brewbuddycafe.com"
            },
            {
                "id": "67890",
                "name": "Bean's Best Coffee",
                "address": "789 10th Avenue, NY",
                "latitude": 40.729610,
                "longitude": -73.934220,
                "category": "cafe",
                "tags": ["open_now", "dog_friendly"],
                "rating": 4.8,
                "opening_hours": {
                    "monday": "7:00 AM - 7:00 PM",
                    "tuesday": "7:00 AM - 7:00 PM",
                    "wednesday": "7:00 AM - 7:00 PM",
                    ...
                },
                "contact": "+1 (345) 678-9012",
                "website": "http://beansbest.com"
            }
            ...
        ]
    },
    "metadata": {
        "total_results": 20,
        "limit": 10,
        "offset": 0,
        "radius": 1000,
        "latitude": 40.730610,
        "longitude": -73.935242
    }
}
				
			

Point of Interest API

Overview

The Point of Interest API enables developers to integrate a vast database of intriguing locations into applications or websites, facilitating the creation of interactive maps and localized services. Offering data on various spots like tourist attractions and restaurants, it ensures enhanced user engagement through personalized experiences.

API Request

Endpoint:

GET /poi

Parameters:
    1. Location Parameters:
      • postal_code : Postal code of the area where points of interest should be retrieved.
      • city : City name to narrow down the search within a specific location.
      • latitude: Latitude of the central point from which to retrieve points of interest.
      • longitude: Longitude of the central point from which to retrieve points of interest.
    1. Search Parameters:
      • query (Optional): A string to search for specific places or types (e.g., “park”, “museum”).
      • category (Optional): Filter results by predefined categories (e.g., “hotel”, “park”). Multiple categories should be supported (e.g., “hotel,park”).
    1. Distance Parameters:
      • radius (Optional): Defines the distance (in meters) within which to return points of interest. The maximum allowable radius may be specified by the API.
    1. Pagination and Sorting:
      • limit (Optional): Maximum number of results to return per response.
      • offset (Optional): Number of results to skip from the start.
      • sort_by (Optional): Parameter to sort results (e.g., “popularity_desc”, “rating_asc”).
    1. Additional Filter Parameters:
      • popularity (Optional): Used to filter places with a certain popularity score or above.
      • rating (Optional): Minimum rating to filter places (e.g., places with a rating of 4 and above).
      • open_now
      • historical (Optional): Boolean parameter to only return places with historical significance.
      • pay_by_card (Optional)
      • wheelchair
      • kid_friendly/dog_friendly (Optional): Boolean parameter to filter results for places that are kid-friendly/dog-friendly.
      • cuisine (Optional): chinese/indian/italian...
      • vegan/vegetarian/pescatarian

Example Request:

				
					https://api.position-lab.com/poi?query=cinema&category=entertainment&city=stockholm&open_now=true&limit:10&api_key=API_KEY
				
			

API Response

				
					{
    "status": "success",
    "count": 10,
    "data": [
        {
            "id": "poi_101",
            "name": "Stockholm Central Cinema",
            "category": "Entertainment",
            "city": "Stockholm",
            "latitude": 59.3293,
            "longitude": 18.0686,
            "open_now": true,
            "rating": 4.5,
            "address": "Sveavägen 20, 111 57 Stockholm, Sweden",
            "description": "Stockholm Central Cinema offers a wide selection of films in a cozy, modern environment. Enjoy the latest releases and timeless classics in the heart of the city.",
            "opening_hours": "10:00 - 22:00",
            "image_url": "https://example.com/images/stockholm_central_cinema.jpg"
        },
        {
            "id": "poi_102",
            "name": "Royal Cinema",
            "category": "Entertainment",
            "city": "Stockholm",
            "latitude": 59.3367,
            "longitude": 18.0728,
            "open_now": true,
            "rating": 4.7,
            "address": "Birger Jarlsgatan 37, 111 45 Stockholm, Sweden",
            "description": "Royal Cinema is an iconic movie theater in Stockholm, known for its royal architecture and selection of independent films.",
            "opening_hours": "12:00 - 23:00",
            "image_url": "https://example.com/images/royal_cinema.jpg"
        },
        {
            "id": "poi_103",
            "name": "Modern Cinema",
            "category": "Entertainment",
            "city": "Stockholm",
            "latitude": 59.3344,
            "longitude": 18.0632,
            "open_now": true,
            "rating": 4.3,
            "address": "Kungsgatan 63, 111 22 Stockholm, Sweden",
            "description": "Modern Cinema brings the latest blockbusters to Stockholm with advanced screening technology and comfortable seating, ensuring a remarkable movie-watching experience.",
            "opening_hours": "11:00 - 21:00",
            "image_url": "https://example.com/images/modern_cinema.jpg"
        }
				
			

Routes API

Overview

The Routes API is a tool that enables users to plan various routes and customize their preferences using filtering parameters according to their own liking.

API Request

Endpoint:

GET /routes

Parameters:
  1. startPoint (Required)

    • Description: Coordinates or address of the starting point of the route.
    • Type: String or Object (for coordinates)
    • Example: "123 Main St, Cityville" or {"lat": 40.748817, "lng": -73.985428}
  2. destination (Required)

    • Description: Coordinates or address of the destination point of the route.
    • Type: String or Object (for coordinates)
    • Example: "456 Elm St, Cityville" or {"lat": 40.748452, "lng": -73.981939}
  3. travelMode (Required)

    • Description: Desired mode of transportation.
    • Type: String
    • Values: "car", "publicTransport", "bicycle", etc.
  4. departureTime (Optional)

    • Description: Preferred departure time.
    • Type: String (ISO 8601 format)
    • Example: "2023-10-20T08:00:00Z"
  5. arrivalTime (Optional)

    • Description: Preferred arrival time.
    • Type: String (ISO 8601 format)
    • Example: "2023-10-20T09:00:00Z"
  6. stops (Optional)

    • Description: Intermediate stops along the route.
    • Type: Array of Strings or Array of Objects (for coordinates)

Example: ["789 Maple St, Cityville"] or [{"lat": 40.748320, "lng": -73.985372}]

Example Request:

				
					https://api.example.com/routes?startPointLat=40.748817&startPointLng=-73.985428&destinationLat=40.748452&destinationLng=-73.981939&transportMode=car&departureTime=2023-10-20T08:00:00Z&arrivalTime=2023-10-20T09:00:00Z&stop1Lat=40.748320&stop1Lng=-73.985372&avoidTolls=true&avoidHighways=false

				
			

API Response

				
					{
"geo_waypoints":
[
{
"status": "OK",
"location_id": "ChIJ9h21D60Fbg0R_t11auhbb8Z",
"types": ["locality", "political"]
},
{
"status": "OK",
"location_id": "ChIJhSwKgZvpQg0XbKMYdHePsR",
"types": ["locality", "political"]
}
],
"routes":
[
{
"bounds":
{
"northeast": { "lat": 42.4165207, "lng": -2.7026134 },
"southwest": { "lat": 41.862808, "lng": -3.029406799999999 }
},
"legs":
[
{
"distance": { "text": "95.3 km", "value": 95327 },
"duration": { "text": "65 mins", "value": 3890 },
"address_end": "Barcelona, Spain",
"location_end": { "lat": 42.4165207, "lng": -2.705076 },
"address_start": "Valencia, Spain",
"location_start": { "lat": 41.862808, "lng": -3.0273727 },
"steps":
[
{
"distance": { "text": "1.6 km", "value": 1615 },
"duration": { "text": "4 mins", "value": 245 },
"end_location":
{ "lat": 41.8681019, "lng": -3.029378299999999 },
"instructions": "Head <b>northeast</b> on <b>Av. de las Naciones</b> toward <b>C. de la Union</b>",
"polyline":
{
"points": "abcdFefgHJIJLJn@PQFg@Ni@JeBh@}@XaD|@{@Vk@Ns@RUFoA^u@R_AXwA@WHMBG@C?E?GAC?IC"
},
"location_start": { "lat": 41.862808, "lng": -3.0273727 },
"travel_mode": "DRIVING"
},
{
"distance": { "text": "2.2 km", "value": 2174 },
"duration": { "text": "2 min", "value": 130 },
"location_end": { "lat": 41.8675297, "lng": -3.0275807 },
"instructions": "At the circle, continue onto <b>C. Marquis de Riscal</b>",
"maneuver": "straight",
"polyline":
{
"points": "efghFr~hW?AAEAEACACACCCACF_@H[FQNi@j@cB`@qAHW"
},
"start_location":
{ "lat": 41.8681019, "lng": -3.029378299999999 },
"travel_mode": "DRIVING"
..............
.........
.....
}
]
}
]