Search locations within a rectangle

curl --request POST \
  --url https://apigwuat.corpay.com/locations/geosearch/rectangle \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filters": {
    "connectorStandards": [
      "Combo"
    ],
    "capabilities": [
      "CHARGING_PROFILE_CAPABLE"
    ]
  },
  "options": {
    "includeAvailableOnly": false
  }
}
'

import requests

url = "https://apigwuat.corpay.com/locations/geosearch/rectangle"

payload = {
    "filters": {
        "connectorStandards": ["Combo"],
        "capabilities": ["CHARGING_PROFILE_CAPABLE"]
    },
    "options": { "includeAvailableOnly": False }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    filters: {connectorStandards: ['Combo'], capabilities: ['CHARGING_PROFILE_CAPABLE']},
    options: {includeAvailableOnly: false}
  })
};

fetch('https://apigwuat.corpay.com/locations/geosearch/rectangle', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://apigwuat.corpay.com/locations/geosearch/rectangle",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'filters' => [
        'connectorStandards' => [
                'Combo'
        ],
        'capabilities' => [
                'CHARGING_PROFILE_CAPABLE'
        ]
    ],
    'options' => [
        'includeAvailableOnly' => false
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://apigwuat.corpay.com/locations/geosearch/rectangle"

	payload := strings.NewReader("{\n  \"filters\": {\n    \"connectorStandards\": [\n      \"Combo\"\n    ],\n    \"capabilities\": [\n      \"CHARGING_PROFILE_CAPABLE\"\n    ]\n  },\n  \"options\": {\n    \"includeAvailableOnly\": false\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://apigwuat.corpay.com/locations/geosearch/rectangle")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filters\": {\n    \"connectorStandards\": [\n      \"Combo\"\n    ],\n    \"capabilities\": [\n      \"CHARGING_PROFILE_CAPABLE\"\n    ]\n  },\n  \"options\": {\n    \"includeAvailableOnly\": false\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://apigwuat.corpay.com/locations/geosearch/rectangle")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filters\": {\n    \"connectorStandards\": [\n      \"Combo\"\n    ],\n    \"capabilities\": [\n      \"CHARGING_PROFILE_CAPABLE\"\n    ]\n  },\n  \"options\": {\n    \"includeAvailableOnly\": false\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "locations": [
    {
      "id": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0gQhJv/Yjp5FXBJt14SccU9zFRdnC4SV7juPdCRaWkEZo=",
      "name": "Ebee Smart Technologies",
      "coordinates": {
        "latitude": "52.475911",
        "longitude": "13.350794"
      },
      "evses": [
        {
          "uid": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJG9qMC0Dp9OqeegGRXmiTOE",
          "evse_id": "+49*839*030*000074",
          "physical_reference": "4",
          "status": "AVAILABLE",
          "connectors": [
            {}
          ],
          "capabilities": [
            "RESERVABLE",
            "PLUG_AND_CHARGE_CAPABLE",
            "PLUG_AND_CHARGE_CAPABLE"
          ],
          "last_updated": "2025-01-15T10:30:00.000Z"
        }
      ],
      "operator": {
        "id": "881941",
        "name": "Ebee Smart Technologies",
        "hotline": "+498944255071",
        "external_id": "DE*ABC"
      },
      "operator_display_name": "Sub-operator X",
      "opening_times": {
        "twentyfourseven": false,
        "regular_hours": [
          {
            "weekday": 1,
            "period_begin": "00:10",
            "period_end": "29:59"
          }
        ],
        "exceptional_openings": [
          {
            "period_begin": "2025-01-15T10:30:00.000Z",
            "period_end": "2025-01-15T10:30:00.000Z"
          }
        ],
        "exceptional_closings": [
          {
            "period_begin": "2025-01-15T10:30:00.000Z",
            "period_end": "2025-01-15T10:30:00.000Z"
          }
        ]
      },
      "directions": [
        {
          "language": "DE",
          "text": "example"
        }
      ],
      "country": "DEU",
      "state": "Bayern",
      "city": "Berlin",
      "postal_code": 10829,
      "address": "EUREF CAMPUS 4-5",
      "openNow": false,
      "is_green_energy": false,
      "last_updated": "2024-03-15T14:30:00.000Z"
    }
  ],
  "aggregates": [
    {
      "coordinates": {
        "latitude": "52.475911",
        "longitude": "13.350794"
      },
      "count": 1
    }
  ]
}

{
  "message": "Invalid request payload",
  "details": [
    "field X is required"
  ]
}

{
  "message": "Resource not found"
}

POST

locations

geosearch

rectangle

Search locations within a rectangle

curl --request POST \
  --url https://apigwuat.corpay.com/locations/geosearch/rectangle \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filters": {
    "connectorStandards": [
      "Combo"
    ],
    "capabilities": [
      "CHARGING_PROFILE_CAPABLE"
    ]
  },
  "options": {
    "includeAvailableOnly": false
  }
}
'

import requests

url = "https://apigwuat.corpay.com/locations/geosearch/rectangle"

payload = {
    "filters": {
        "connectorStandards": ["Combo"],
        "capabilities": ["CHARGING_PROFILE_CAPABLE"]
    },
    "options": { "includeAvailableOnly": False }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    filters: {connectorStandards: ['Combo'], capabilities: ['CHARGING_PROFILE_CAPABLE']},
    options: {includeAvailableOnly: false}
  })
};

fetch('https://apigwuat.corpay.com/locations/geosearch/rectangle', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://apigwuat.corpay.com/locations/geosearch/rectangle",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'filters' => [
        'connectorStandards' => [
                'Combo'
        ],
        'capabilities' => [
                'CHARGING_PROFILE_CAPABLE'
        ]
    ],
    'options' => [
        'includeAvailableOnly' => false
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://apigwuat.corpay.com/locations/geosearch/rectangle"

	payload := strings.NewReader("{\n  \"filters\": {\n    \"connectorStandards\": [\n      \"Combo\"\n    ],\n    \"capabilities\": [\n      \"CHARGING_PROFILE_CAPABLE\"\n    ]\n  },\n  \"options\": {\n    \"includeAvailableOnly\": false\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://apigwuat.corpay.com/locations/geosearch/rectangle")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filters\": {\n    \"connectorStandards\": [\n      \"Combo\"\n    ],\n    \"capabilities\": [\n      \"CHARGING_PROFILE_CAPABLE\"\n    ]\n  },\n  \"options\": {\n    \"includeAvailableOnly\": false\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://apigwuat.corpay.com/locations/geosearch/rectangle")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filters\": {\n    \"connectorStandards\": [\n      \"Combo\"\n    ],\n    \"capabilities\": [\n      \"CHARGING_PROFILE_CAPABLE\"\n    ]\n  },\n  \"options\": {\n    \"includeAvailableOnly\": false\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "locations": [
    {
      "id": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0gQhJv/Yjp5FXBJt14SccU9zFRdnC4SV7juPdCRaWkEZo=",
      "name": "Ebee Smart Technologies",
      "coordinates": {
        "latitude": "52.475911",
        "longitude": "13.350794"
      },
      "evses": [
        {
          "uid": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJG9qMC0Dp9OqeegGRXmiTOE",
          "evse_id": "+49*839*030*000074",
          "physical_reference": "4",
          "status": "AVAILABLE",
          "connectors": [
            {}
          ],
          "capabilities": [
            "RESERVABLE",
            "PLUG_AND_CHARGE_CAPABLE",
            "PLUG_AND_CHARGE_CAPABLE"
          ],
          "last_updated": "2025-01-15T10:30:00.000Z"
        }
      ],
      "operator": {
        "id": "881941",
        "name": "Ebee Smart Technologies",
        "hotline": "+498944255071",
        "external_id": "DE*ABC"
      },
      "operator_display_name": "Sub-operator X",
      "opening_times": {
        "twentyfourseven": false,
        "regular_hours": [
          {
            "weekday": 1,
            "period_begin": "00:10",
            "period_end": "29:59"
          }
        ],
        "exceptional_openings": [
          {
            "period_begin": "2025-01-15T10:30:00.000Z",
            "period_end": "2025-01-15T10:30:00.000Z"
          }
        ],
        "exceptional_closings": [
          {
            "period_begin": "2025-01-15T10:30:00.000Z",
            "period_end": "2025-01-15T10:30:00.000Z"
          }
        ]
      },
      "directions": [
        {
          "language": "DE",
          "text": "example"
        }
      ],
      "country": "DEU",
      "state": "Bayern",
      "city": "Berlin",
      "postal_code": 10829,
      "address": "EUREF CAMPUS 4-5",
      "openNow": false,
      "is_green_energy": false,
      "last_updated": "2024-03-15T14:30:00.000Z"
    }
  ],
  "aggregates": [
    {
      "coordinates": {
        "latitude": "52.475911",
        "longitude": "13.350794"
      },
      "count": 1
    }
  ]
}

{
  "message": "Invalid request payload",
  "details": [
    "field X is required"
  ]
}

{
  "message": "Resource not found"
}

Authorizations

Authorization

string

header

required

Use OAuth2 client credentials to obtain a bearer token.

Token endpoint: POST <BASE_URL>/keycloak/realms/longship/protocol/openid-connect/token

Use the same base URL as the selected API server:

Test environment: https://apigwuat.corpay.com
Production environment: https://apigw.corpay.com

Example:

curl --location '<BASE_URL>/keycloak/realms/longship/protocol/openid-connect/token' \
--header 'accept: application/json' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=.......' \
--data-urlencode 'client_secret=......'

Query Parameters

topLatitude

number<double>

required

Latitude of the top edge of the rectangle in decimal degrees (e.g. N58°30' is represented as 58.5). Must be greater than bottomLatitude.

Required range: -90 <= x <= 90

bottomLatitude

number<double>

required

Latitude of the bottom edge of the rectangle in decimal degrees (e.g. S58°30' is represented as -58.5)

Required range: -90 <= x <= 90

leftLongitude

number<double>

required

Longitude of the left edge of the rectangle in decimal degrees (e.g. E014°45' is represented as 14.75). Must be less than rightLongitude.

Required range: -180 <= x <= 180

rightLongitude

number<double>

required

Longitude of the right edge of the rectangle in decimal degrees (e.g. E014°45' is represented as 14.75)

Required range: -180 <= x <= 180

limit

number

default:300

Number of locations returned in the response (doesn't apply when aggregation is enabled)

Required range: x <= 300

aggregate

boolean

default:false

If true, the results will be aggregated. For large radius it makes the response much faster.

aggregationPrecision

integer

Value between 2 and 9. The bigger value is, the smaller is the cell size of the grid for aggregation. If not passed, a default value, based on radius, is assumed.

Required range: 2 <= x <= 9

language

string

Supported languages: en, bg, cy, de, es, fi, fr, hu, is, it, lt, nb, nl, pl, pt, ro, sv.

Required string length: 2

Body

application/json

Geosearch request constrained to a rectangular area.

filters

object

Filtering criteria for location selection.

Show child attributes

options

object

Additional options controlling search behavior.

Show child attributes

Response

Response payload containing matching locations and aggregate metadata for a geosearch query.

locations

object[]

required

Locations matching the geosearch criteria.

Show child attributes

aggregates

object[]

Present only if 'aggregate' request param = true. Contains only aggregates of 2 or more locations. Single locations are returned in 'locations' array.

Show child attributes

⌘I