> ## Documentation Index > Fetch the complete documentation index at: https://api.corpay.com/llms.txt > Use this file to discover all available pages before exploring further. # Search locations within a rectangle > Search for charging locations within a specified rectangle defined by two diagonal points. The rectangle coordinates are passed via the `topLatitude`, `bottomLatitude`, `leftLongitude`, and `rightLongitude` query parameters; the request body contains only filters and options. Returns up to 300 locations. ## OpenAPI ````yaml /openapi.yaml post /locations/geosearch/rectangle openapi: 3.1.0 info: title: Corpay APIs version: 1.0.0 description: > Corpay APIs for customer profile management, card management, transaction history, and master data retrieval. servers: - url: https://apigwuat.corpay.com description: Test environment - url: https://apigw.corpay.com description: Production environment security: - oauth2ClientCredentials: [] tags: - name: Customer description: Customer profile and account lifecycle APIs - name: Card description: Card retrieval, ordering and lifecycle APIs - name: Geosearch description: >- Search and retrieve detailed information about charging locations and stations - name: Remote Charging description: >- Control charging sessions remotely including starting and stopping sessions, and monitoring session status - name: EV Session description: >- Access and manage charging session data including history, status, and detailed session information - name: Transaction description: Transaction history APIs - name: Master description: Master/reference data APIs - name: Webhooks description: Event callback payloads sent by Corpay paths: /locations/geosearch/rectangle: post: tags: - Geosearch summary: Search locations within a rectangle description: >- Search for charging locations within a specified rectangle defined by two diagonal points. The rectangle coordinates are passed via the `topLatitude`, `bottomLatitude`, `leftLongitude`, and `rightLongitude` query parameters; the request body contains only filters and options. Returns up to 300 locations. operationId: searchLocationsByRectangle parameters: - name: topLatitude in: query required: true description: >- 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. example: 52.354551 schema: type: number format: double minimum: -90 maximum: 90 - name: bottomLatitude in: query required: true description: >- Latitude of the bottom edge of the rectangle in decimal degrees (e.g. S58°30' is represented as -58.5) example: 52.354551 schema: type: number format: double minimum: -90 maximum: 90 - name: leftLongitude in: query required: true description: >- 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. example: 4.7391593 schema: type: number format: double minimum: -180 maximum: 180 - name: rightLongitude in: query required: true description: >- Longitude of the right edge of the rectangle in decimal degrees (e.g. E014°45' is represented as 14.75) example: 4.7391593 schema: type: number format: double minimum: -180 maximum: 180 - name: limit in: query description: >- Number of locations returned in the response (doesn't apply when aggregation is enabled) schema: type: number maximum: 300 default: 300 - name: aggregate in: query description: >- If true, the results will be aggregated. For large radius it makes the response much faster. required: false schema: type: boolean default: false - name: aggregationPrecision in: query description: >- 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: false schema: type: integer minimum: 2 maximum: 9 - name: language schema: type: string minLength: 2 maxLength: 2 in: query required: false example: en description: >- Supported languages: en, bg, cy, de, es, fi, fr, hu, is, it, lt, nb, nl, pl, pt, ro, sv. requestBody: content: application/json: schema: $ref: '#/components/schemas/DriveRectangleRequest' example: filters: connectorStandards: - Combo capabilities: - CHARGING_PROFILE_CAPABLE options: includeAvailableOnly: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DriveBaseResponseListLocation' example: 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 '400': description: The provided query parameters, route parameters or body is invalid. content: application/json: schema: $ref: '#/components/schemas/DriveInvalidRequestErrorResponse' example: message: Invalid request payload details: - field X is required '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/DriveErrorResponse' example: message: Resource not found components: schemas: DriveRectangleRequest: description: Geosearch request constrained to a rectangular area. example: filters: locationStatuses: - AVAILABLE - CHARGING - OCCUPIED - RESERVED - UNKNOWN - OUTOFORDER powerType: AC properties: filters: $ref: '#/components/schemas/DriveGeoFilters' description: Filtering criteria for location selection. options: $ref: '#/components/schemas/DriveGeoOptions' description: Additional options controlling search behavior. type: object DriveBaseResponseListLocation: description: >- Response payload containing matching locations and aggregate metadata for a geosearch query. properties: aggregates: description: >- Present only if 'aggregate' request param = true. Contains only aggregates of 2 or more locations. Single locations are returned in 'locations' array. items: $ref: '#/components/schemas/DriveAggregate' type: array locations: description: Locations matching the geosearch criteria. items: $ref: '#/components/schemas/DriveLocation' type: array required: - locations type: object DriveInvalidRequestErrorResponse: properties: fields: items: properties: message: example: UserId is not correct type: string name: type: string rejectedValue: type: string required: - name - message - rejectedValue title: InvalidField type: object type: array message: type: string required: - message - fields title: InvalidRequestErrorResponse type: object DriveErrorResponse: properties: message: type: string title: ErrorResponse type: object DriveGeoFilters: description: Filtering criteria applied to geosearch requests. properties: capabilities: description: Required EVSE capabilities. items: $ref: '#/components/schemas/DriveCapabilities' type: array connectorStandards: description: Accepted connector standards. items: $ref: '#/components/schemas/DriveConnectorStandard' type: array countries: description: Array of 3-letter country codes items: example: - NOR - SWE - DEU type: string type: array evseIds: description: Return only stations with evses id match a pattern example: - +49*839 - '*075*000075' items: type: string type: array excludedOperatorIds: description: >- Exclude stations from these operators. (This parameter will be ignored when operatorIds are provided.) items: type: integer type: array locationStatuses: description: >- Only return locations whose status is included in this list. A common default is `[AVAILABLE, CHARGING, OCCUPIED, RESERVED, UNKNOWN, OUTOFORDER]`, which excludes statuses such as `BLOCKED`, `INOPERATIVE`, `OFFLINE`, and `REMOVED`. example: - AVAILABLE - CHARGING - OCCUPIED - RESERVED - UNKNOWN - OUTOFORDER items: $ref: '#/components/schemas/DriveConnectorStatus' type: array open247: description: Return only stations open 24/7. type: boolean openNow: description: >- Returns only stations now opened (based on data provided by CPOs). This parameter is not supported with aggregations. type: boolean operatorIds: description: >- Get stations only from these operators. (When provided, excludedOperatorIds will be ignored.) items: type: integer type: array power: description: Minimum power in W example: 30000 type: integer powerType: description: AC filter will contain both AC 1-phase and 3-phase. enum: - AC - DC type: string type: object DriveGeoOptions: description: Additional geosearch options for shaping returned results. properties: filterEvsesAndConnectors: description: >- Filter out connectors and evses which don't match filters params. Significantly decreases payload if non-matching objects are not needed. type: boolean type: object DriveAggregate: properties: coordinates: $ref: '#/components/schemas/DriveCoordinates' description: Aggregate center coordinates returned as strings. count: description: Number of locations around this point. minimum: 2 type: integer required: - coordinates - count type: object DriveLocation: properties: address: description: Street address of the charging location example: EUREF CAMPUS 4-5 type: string city: description: City where the charging location is situated example: Berlin type: string coordinates: $ref: '#/components/schemas/DriveCoordinates' description: >- Geographic coordinates of the charging location. These values are returned as strings. country: description: >- Three-letter country code (ISO 3166-1 alpha-3) where the charging location is situated example: DEU maxLength: 3 minLength: 3 type: string directions: description: >- Navigation instructions to help locate the charging points, available in multiple languages items: $ref: '#/components/schemas/DriveDisplayText' type: array evses: description: >- List of Electric Vehicle Supply Equipment (EVSE) at this location. Each EVSE may have multiple connectors. items: $ref: '#/components/schemas/DriveEvse' type: array id: example: >- 8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0gQhJv/Yjp5FXBJt14SccU9zFRdnC4SV7juPdCRaWkEZo= minLength: 0 type: string is_green_energy: description: >- Indicates if the location uses renewable energy sources for charging, based on CPO-provided data example: false type: boolean last_updated: description: >- ISO 8601 timestamp of when this location's data was last updated. Use this to track changes and implement efficient polling. example: '2024-03-15T14:30:00.000Z' type: string name: description: Human-readable name of the charging location example: Ebee Smart Technologies maxLength: 255 minLength: 0 type: string openNow: description: >- Indicates if the location is currently open based on opening_hours and local timezone. Use this for quick filtering of available locations. example: false type: boolean opening_times: $ref: '#/components/schemas/DriveOpeningTimes' description: Operating hours of the charging location operator: $ref: '#/components/schemas/DriveBusinessDetails' description: >- Information about the Charging Point Operator (CPO) managing this location operator_display_name: description: >- An enhanced display name of the operator. This may be the operator name as found in the operator object, or the sub-operator of the location. When showing the location to end users, this is the operator name that should be shown. example: Sub-operator X type: string postal_code: description: Postal code of the charging location example: 10829 type: string state: description: >- State, region, or province where the charging location is situated. Format varies by country. example: Bayern type: string required: - id - name - coordinates - address - evses - country - city - last_updated type: object DriveCapabilities: enum: - REMOTE_START_STOP_CAPABLE - PLUG_AND_CHARGE_CAPABLE type: string DriveConnectorStandard: description: >- Connector standard accepted by the API. Use `Combo` for CCS connectors. `CHADEMO` is the preferred token; `Chademo` is a legacy alias. enum: - 3PinSquare - Cee2Poles - CeeBlue - CeePlus - CeeRed - Combo - Marechal - Nema5 - Scame - CHADEMO - Chademo - Type1 - Type2 - Type3 - TypeE - Schuko - UNKNOWN - T23 - T13 - T15 - Tesla - DOMESTIC_A - DOMESTIC_B - DOMESTIC_C - DOMESTIC_D - DOMESTIC_E - DOMESTIC_F - DOMESTIC_G - DOMESTIC_H - DOMESTIC_I - DOMESTIC_J - DOMESTIC_K - DOMESTIC_L - IEC_60309_2_single_16 - IEC_60309_2_three_16 - IEC_60309_2_three_32 - IEC_60309_2_three_64 - IEC_62196_T1 - IEC_62196_T1_COMBO - IEC_62196_T2 - IEC_62196_T2_COMBO - IEC_62196_T3A - IEC_62196_T3C - TESLA_R - TESLA_S example: Type2 type: string DriveConnectorStatus: enum: - AVAILABLE - CHARGING - BLOCKED - INOPERATIVE - OCCUPIED - OFFLINE - OUTOFORDER - PLANNED - REMOVED - RESERVED - UNKNOWN - UNAVAILABLE example: AVAILABLE type: string DriveCoordinates: description: >- Latitude and longitude values serialized as strings with fixed decimal precision. This schema is used in response payloads and in route-search points. properties: latitude: description: Latitude serialized as a string, for example `52.475911`. example: '52.475911' pattern: '-?[0-9]{1,2}\.[0-9]{6}' type: string longitude: description: Longitude serialized as a string, for example `13.350794`. example: '13.350794' pattern: '-?[0-9]{1,3}\.[0-9]{6}' type: string type: object DriveDisplayText: properties: language: example: DE maxLength: 2 minLength: 2 type: string text: example: example maxLength: 512 type: string required: - language - text type: object DriveEvse: description: >- Electric Vehicle Supply Equipment (EVSE) represents a charging station unit that may have multiple connectors. Only one connector can be active at a time. properties: capabilities: description: >- Values: `PLUG_AND_CHARGE_CAPABLE`, `REMOTE_START_STOP_CAPABLE`. New values in this array might be added without notice, so unknown values should be handled gracefully. example: - RESERVABLE - PLUG_AND_CHARGE_CAPABLE - PLUG_AND_CHARGE_CAPABLE items: type: string type: array connectors: items: $ref: '#/components/schemas/DriveConnector' type: array evse_id: example: +49*839*030*000074 minLength: 1 type: string last_updated: format: date-time type: string physical_reference: description: >- The 'physical reference' is used by some CPOs to represent the label printed on the charging station itself. For example, in a charging location, the physical references could be '1', '2', '3', '4', for the four different charging stations example: '4' type: string status: $ref: '#/components/schemas/DriveConnectorStatus' uid: example: >- 8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJG9qMC0Dp9OqeegGRXmiTOE minLength: 0 type: string required: - uid - status - connectors - capabilities - last_updated type: object DriveOpeningTimes: properties: exceptional_closings: items: $ref: '#/components/schemas/DriveExceptionalPeriod' type: array exceptional_openings: items: $ref: '#/components/schemas/DriveExceptionalPeriod' type: array regular_hours: items: $ref: '#/components/schemas/DriveRegularHours' type: array twentyfourseven: example: false type: boolean required: - twentyfourseven type: object DriveBusinessDetails: properties: external_id: example: DE*ABC type: string hotline: example: '+498944255071' type: string id: example: '881941' type: string name: example: Ebee Smart Technologies maxLength: 100 minLength: 0 type: string required: - id - name type: object DriveConnector: properties: id: description: >- Unique identifier for this connector. Use this ID when starting charging sessions. example: >- 8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJEM0D69tJVN05/1hZ1zxqZSJ9kBdNsmfryS0+gvjLNZvdF1pDHJuCTydsJX6vPZh7U= minLength: 0 type: string max_amperage: description: Maximum current in Amperes that this connector can provide example: 32 type: number max_voltage: description: Maximum voltage in Volts that this connector can provide example: 400 type: number power: description: >- Maximum power output in Watts. For AC chargers, this is typically between 3.7kW and 43kW. For DC chargers, typically between 50kW and 350kW. example: 22000 type: integer power_type: enum: - AC_1_PHASE - AC_3_PHASE - DC - AC example: AC_3_PHASE type: string price: description: >- Pricing information for this connector. Only available when retrieving a specific location. properties: currency: description: >- Three-letter currency code ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format) example: EUR type: string description: description: Human-readable description of the pricing structure example: € 0.56/kWh, € 0.10/min (> 2 h) type: string elements: description: Possible prices for that connector, depending on restrictions items: $ref: '#/components/schemas/DrivePriceElement' type: array id: example: 4370769f30bd7927 type: string priceIncludesVat: description: >- Indicates whether the price includes VAT or not (same meaning as for the CDR object) example: 'true' type: boolean vatRate: description: >- The VAT rate that is applied to the price (in case priceIncludesVat=true) or the VAT rate that should be applied to the price (in case priceIncludesVat=false) example: '22' type: string type: object standard: $ref: '#/components/schemas/DriveConnectorStandard' description: >- Physical connector type/standard (e.g., Type2, Combo, CHADEMO). Use `Combo` for CCS connectors. required: - id - standard - power_type type: object DriveExceptionalPeriod: properties: period_begin: format: date-time type: string period_end: format: date-time type: string required: - period_begin - period_end DriveRegularHours: description: Only to be used if twentyfourseven = false properties: period_begin: example: '00:10' format: ([0-1][0-9]|2[0-3]):[0-5][0-9] type: string period_end: example: '29:59' format: ([0-1][0-9]|2[0-3]):[0-5][0-9] type: string weekday: description: Number of day in the week, from Monday (1) till Sunday (7) example: 1 type: integer required: - weekday - period_begin - period_end DrivePriceElement: description: >- Defines a complete pricing structure that may apply under certain conditions. Multiple price elements may exist for different times or usage patterns. properties: price_components: description: >- List of individual price components that make up this pricing structure items: $ref: '#/components/schemas/DrivePriceComponent' type: array restrictions: description: >- Conditions under which this price element applies. Multiple restrictions can be combined. properties: day_of_week: description: Days of the week when this price applies enum: - MONDAY - TUESDAY - WEDNESDAY - THURSDAY - FRIDAY - SATURDAY - SUNDAY example: - MONDAY - TUESDAY - WEDNESDAY - THURSDAY - FRIDAY type: string end_time: description: >- Time of day when this price stops applying (local time at the charging location) example: '22:30' type: string max_congestion_threshold: description: >- Maximum congestion threshold of the location, congestion fee will apply to valid x% example: 90 type: number max_duration: description: Maximum charging duration in seconds for this price to apply example: 10000 type: number max_kwh: description: Maximum energy consumption in kWh for this price to apply example: 5 type: number min_congestion_threshold: description: >- Minimum congestion threshold of the location, congestion fee will apply from valid x% example: 70 type: number min_duration: description: >- Minimum charging duration in seconds before this price applies (e.g., 7200 means this price applies after 2 hours) example: 7200 type: number min_kwh: description: Minimum energy consumption in kWh before this price applies example: 2 type: number min_vehicle_soc: description: >- Minimum vehicle state of charge in percentage, valid for vehicle state of charge from x% example: 80 type: number start_time: description: >- Time of day when this price starts applying (local time at the charging location) example: '08:30' type: string type: object required: - price_components type: object DrivePriceComponent: description: >- Defines a single component of a charging price. A price can have multiple components (e.g., energy cost + time cost). properties: price: description: >- Cost in the currency stated above. VAT is included. Decimal number. For example, if currency is EUR and price is 1.10, the cost is €1.10. More information can be found in https://developer.plugsurfing.com/docs/geosearch#explanation example: 0 type: number step_size: description: >- The smallest unit of usage that will be billed. Unit: seconds for `TIME` and `PARKING_TIME`, watt-hours (Wh) for `ENERGY`. More information can be found in https://developer.plugsurfing.com/docs/geosearch#explanation example: 1 type: number type: description: >- More information can be found in https://developer.plugsurfing.com/docs/geosearch#explanation enum: - TIME - ENERGY - FLAT - CAPPED example: FLAT type: string type: object securitySchemes: oauth2ClientCredentials: description: > Use OAuth2 client credentials to obtain a bearer token. Token endpoint: `POST /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: ```bash curl --location '/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=......' ``` flows: clientCredentials: scopes: {} tokenUrl: /keycloak/realms/longship/protocol/openid-connect/token type: oauth2 ````