Reverse Geocoding

There are two reversegeo APIs, the first one is /reversegeo this one returns the names of any geofences found in the location you pass it, as well as an address. The second reversegeo api is maps.pegasusgateway.com/reversegeo which is more up to date in terms of the addresses it returns and is capable of returning bulk addresses in multiple language formats, read below to find out.

/reversegeo

Single result

The GET request can be used to retrieve a single lat,lon result.

GET /reversegeo params

/reversegeo?lat=25.9865&lon=-80.11959&zones=true&nearby=5000&types=193

The response will show :

• zones: name of any geofence that this point is in. The geofence will be displayed depending on its property Visibility.
• location_full: address of the location. If the zone parameter is set true, then location_full include the name of the geofence.
• address: address of the location.
• nearby: the API returns the geofences within the specified radius. The response lists the first 15 geofences ordered ascending by distance. If the request includestypes = id_collection, the response will list the first 15 geofences included in the collection_id ordered by distance. The nearby property contains:
  • distance: distance(meters) from the location to the geofence.
  • id: id related to /geofences.
  • name: name of the geofence.
  • custom: the user can specify custom properties using the custom key in the geofence properties. This accepts any JSON object value. There is a special custom boolean property called: $checkpoint that is added with a true value when the geofence is a point of interest.

{
    "zones": [
        "circle geofence"
    ],
    "location_full": "circle geofence 33009, Hollywood, Hallandale Beach, Broward County, Florida, US",
    "do_resolve_map": true,
    "nearby": [
        {
            "distance": 0,
            "id": 22528,
            "name": "circle geofence",
            "custom": {
              "$checkpoint": true,
                "foo": 1
            }
        },
        {
            "distance": 2385,
            "id": 13189,
            "name": "95 Segment above 826",
            "custom": {}
        },
        {
            "distance": 2849,
            "id": 4717,
            "name": "Mall",
            "custom": {
                "owner": "ADMIN",
                "retail": "true",
                "amount of stores": 100
            }
        }
    ],
    "address": "33009, Hollywood, Hallandale Beach, Broward County, Florida, US"
}

📘

Point of Interest

The points of interest will be all geofences with circular type and radius 50m that the user specify as a Point of Interest. In the Api we can add the $checkpoint:true when we create the geofence. In the user interface, the user can specify this property in the Geofence Create/Edit dialog, checking the Point of Interest option.

📘

Types

This parameter was created with the objective of showing the POI close to the point. If you do not specify this parameter, the response will show the first 15 geofences near the point sorted by distance, even if they are POI or not. If you add thetypes parameter, the response will include the first 15 geofences that belong to the collection and are close to the point. The geofences will be ordered by ascending by distance.

Multiple results

With the POST method you can pass up to 50 latitude, longitude pairs.

When you send multiple points you must specify a key, this will help you identify which json object corresponds to which lat, lon requested

POST /reversegeo

multiple lat lon pairs (up to 50)

POST /reversegeo?zones=true&nearby=5000

[
  {
    "key": "one",
    "lat": 25.78362,
    "lon": -80.293265
  },
  {
    "key": "two",
    "lat": 2.2006,
    "lon": -76.8197
  }
]

Result: 200 OK

{
    "two": {
        "zones": [
            "CAUCA"
        ],
        "location_full": "CAUCA La Sierra, Macizo, Cauca, CO",
        "do_resolve_map": true,
        "nearby": [
            {
                "distance": 0,
                "id": 4659,
                "name": "CAUCA",
                "custom": {
                    "owner": "ADMIN",
                    "type": "Circle",
                    "$checkpoint": true,
                    "collections": "167",
                    "id": 4659,
                    "visibility": "groups"
                }
            }
        ],
        "address": "La Sierra, Macizo, Cauca, CO"
    },
    "one": {
        "zones": [
            "DCT Headquarter"
        ],
        "location_full": "DCT Headquarter 33126, Miami-Dade County, Florida, US",
        "do_resolve_map": true,
        "nearby": [
            {
                "distance": 0,
                "id": 46222,
                "name": "DCT Headquarter",
                "custom": {}
            },
            {
                "distance": 28,
                "id": 7480,
                "name": "Laguna Azul",
                "custom": {
                    "visibility": "groups",
                    "collections": "465",
                    "speed_limit": 35,
                    "owner": "ADMIN",
                    "type": "Polygon",
                    "id": 7480
                }
            },
            {
                "distance": 1598,
                "id": 1750,
                "name": "Triton Of.230",
                "custom": {}
            }                    
        ],
        "address": "33126, Miami-Dade County, Florida, US"
    }
}

maps/reversegeo

The maps/reversegeo reverse geocoding API allows you to convert lat,lon coordinates into a human-readable address. The API synchronizes daily with OSM to bring the latest address information. The neat thing is this means you can edit something on OSM and see it reflected on the reversegeo API. Another notable difference is that this API does not provide the zones information like the /reversegeo one does. This api also features the posted speed limits response, allowing you to get the speed limits posted on the road of the address that it resolved.

maps API endpoint https://maps.pegasusgateway.com/reversegeo

Single result

For a single address request you can make a GET request with the following URL params

• Synth method is forced to "amia_text"

reversegeo?r=25.78362,-80.293265

{
    "errors": {},
    "results": {
        "025.78362000:-080.29327000": "5835 Blue Lagoon Drive. MIAMI-DADE COUNTY, FL 33126 US"
    }
}

reversegeo?r=25.78445,-80.29373&fmt={$speed-limit}

{
  "errors": {},
  "results": {
    "025.78445000:-080.29373000": "88"
  }
}

reversegeo?r=25.78445,-80.29373&fmt={$one-line,speed-limit}

# posted speed limit is shown in km/h
{
  "errors": {},
  "results": {
    "025.78445000:-080.29373000": [
      "Dolphin Expressway. MIAMI-DADE COUNTY, FL 33126 US",
      "88" 
    ]
  }
}

Multiple results

The POST method is used to pass single or multi line lat,lon reverse geocoding

• Authenticate header required: Any token from a valid pegasus session
• Rates: Per user, site, and global. Rate control is not based on number of POST requests but on number of locations requests for reverse-geo processing. Enforced via http 429. On 429, current returned object is pretty crude, and gives no info on when the ban is lifted, however, indication of which rate is violated is given.

Request object keys

• list: A list of lat-lon objects to resolve (max 100 per call)
  • lat-lon Object with lat lon, optional key, optional synth
• return_as: String: dict|list: Indicates how to return results. list yields to a list with the same size
  as the passe one. dict returns a dict whose keys are either the key passed on the lat-lon object, otherwise, an internally constructed key representaing the lat+lon object
• synth: Object. Controls how data results are returned/formatted. This object may be defined also per lat-lon object to override the request-wide set. This should be used when some of the lat-lon objects on list need to be synthetized different than the majority of items.

synth keys:

• method: String. Method to process:
  • 'std_text': return text. Legacy format
  • 'amia_text': return text. An fmt argument may be passed to format the result. An include_data boolean may be passed so that data objects, as well as text is returned.
  • 'reduced': Returns an useful object to play with.
  • If method is not passed, a long debug object is returned.
• 'lang': String (en|es|it|fr|... etc). When available, try to return names in this language.
• 'fmt': For amia_text method. An interpolation string to format the returned text. Some fields to pick: Interpolation: python formatter. Use !u and !l to convert upper, lower case, see combos below for examples

Address formatting options (fmt)

Combo formatting options

fmt options

{$multi-line}

137 Pilkington Avenue 
SUTTON COLDFIELD
BIRMINGHAM
B72 GB

{$one-line}

137 Pilkington Avenue. SUTTON COLDFIELD, B72 BIRMINGHAM GB

{$two-line}

137 Pilkington Avenue
SUTTON COLDFIELD, B72 BIRMINGHAM GB

{$one-line-short}

137 Pilkington Avenue. SUTTON COLDFIELD

basic "return_as": "dict"

body

{
  "list": [
    {
      "lat": 25.7711,
      "lon": -80.2774
    },
    {
      "lat": 52.54874,
      "lon": -1.81602
    },
    {
      "lat": 4.6702,
      "lon": -74.0541
    }
  ],
  "synth": {
    "method": "amia_text",
    "lang": "es"
  },
  "return_as": "dict"
}

response

{
  "errors": {},
  "results": {
    "025.77110000:-080.27740000": "5050 West Flagler Street. MIAMI, 33134 FL US",
    "052.54874000:-001.81602000": "137 Pilkington Avenue. SUTTON COLDFIELD, B72 BIRMINGHAM GB",
    "004.67020000:-074.05410000": "Carrera 14 85-68. CHAPINERO, BOGOTÁ CO"
  }
}

dict with custom keys

body

# POST body
{
  "list": [
    {
      "lat": 25.7711,
      "lon": -80.2774,
      "key": "mykey1"
    },
    {
      "lat": 52.54874,
      "lon": -1.81602,
      "key": "mykey2"
    },
    {
      "lat": 4.6702,
      "lon": -74.0541,
      "key": "mykey3"
    }
  ],
  "synth": {
    "method": "amia_text",
    "lang": "es"
  },
  "return_as": "dict"
}

response

{
  "errors": {},
  "results": {
    "mykey3": "Carrera 14 85-68. CHAPINERO, BOGOTÁ CO",
    "mykey2": "137 Pilkington Avenue. SUTTON COLDFIELD, B72 BIRMINGHAM GB",
    "mykey1": "5050 West Flagler Street. MIAMI, 33134 FL US"
  }
}