Skip to content

Commit 1a58acf

Browse files
committed
Support Search API v2
1 parent 3bdc4c4 commit 1a58acf

144 files changed

Lines changed: 334 additions & 156 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

CHANGELOG.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
66
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
77

8+
## Version 8.0.0 - 2025-06-12
9+
10+
### Added
11+
12+
- Support for the v2 `search` (forward geocoding) endpoint! The new API includes better structure, more details, and better address formatting.
13+
14+
```diff
15+
- const res = await api.search({
16+
+ const res = await api.searchV2({
17+
text: 'Telliskivi 60a/3, Tallinn, Estonia'
18+
});
19+
```
20+
21+
For an overview of the structural changes we've made in the V2 API,
22+
refer to the [migration guide](https://docs.stadiamaps.com/geocoding-search-autocomplete/v2-api-migration-guide/).
23+
24+
### Fixed
25+
26+
- **Potentially breaking change:** The `maneuvers` property on route responses was previously marked as required.
27+
However, it is possible to explicitly request routes with this field removed.
28+
These would fail validation and the whole request would end with an exception
29+
in the API client.
30+
This has been fixed in this version, so the property is optional.
31+
832
## Version 7.3.0 - 2025-06-03
933

1034
### Added

__tests__/geocoding.test.ts

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -542,8 +542,15 @@ describe("GeocodingApi V2 unit tests", () => {
542542
test("autocomplete endpoint integration test", async () => {
543543
const res = await api.autocompleteV2({ text: address, lang: "en" });
544544
expect(res.features.length).toBeGreaterThanOrEqual(1);
545-
expect(res.features[0]?.properties?.context).toBeUndefined();
546-
expect(res.features[0]?.properties?.layer).toEqual("address");
545+
expect(res.features[0]?.properties.context).toBeUndefined();
546+
expect(res.features[0]?.properties.layer).toEqual("address");
547+
});
548+
549+
test("search endpoint integration test", async () => {
550+
const res = await api.searchV2({ text: address });
551+
expect(res.features.length).toBeGreaterThanOrEqual(1);
552+
expect(res.features[0]?.properties.context?.iso3166A3).toEqual("EST");
553+
expect(res.features[0]?.properties.layer).toEqual("address");
547554
});
548555

549556
test("place endpoint integration test", async () => {
@@ -553,10 +560,10 @@ describe("GeocodingApi V2 unit tests", () => {
553560
});
554561
expect(res.features).toHaveLength(1);
555562
expect(
556-
res.features[0]?.properties?.context?.whosonfirst?.country?.name,
563+
res.features[0]?.properties.context?.whosonfirst?.country?.name,
557564
).toEqual("Estonia");
558-
expect(res.features[0]?.properties?.context?.iso3166A3).toEqual("EST");
559-
expect(res.features[0]?.properties?.layer).toEqual("address");
565+
expect(res.features[0]?.properties.context?.iso3166A3).toEqual("EST");
566+
expect(res.features[0]?.properties.layer).toEqual("address");
560567
});
561568

562569
test("reverse endpoint integration test", async () => {
@@ -566,7 +573,7 @@ describe("GeocodingApi V2 unit tests", () => {
566573
lang: "en",
567574
});
568575
expect(res.features.length).toBeGreaterThanOrEqual(1);
569-
expect(res.features[0]?.properties?.context?.iso3166A3).toEqual("EST");
576+
expect(res.features[0]?.properties.context?.iso3166A3).toEqual("EST");
570577
});
571578

572579
test("reverse endpoint explicit layer integration test", async () => {
@@ -577,8 +584,8 @@ describe("GeocodingApi V2 unit tests", () => {
577584
lang: "en",
578585
});
579586
expect(res.features.length).toBeGreaterThanOrEqual(1);
580-
expect(res.features[0]?.properties?.context?.iso3166A3).toEqual("EST");
581-
expect(res.features[0]?.properties?.layer).toEqual("address");
587+
expect(res.features[0]?.properties.context?.iso3166A3).toEqual("EST");
588+
expect(res.features[0]?.properties.layer).toEqual("address");
582589
});
583590

584591
test("reverse endpoint uncommon layer integration test", async () => {
@@ -588,7 +595,7 @@ describe("GeocodingApi V2 unit tests", () => {
588595
lang: "en",
589596
});
590597
expect(res.features.length).toBeGreaterThanOrEqual(1);
591-
expect(res.features[0]?.properties?.layer).toEqual("marinearea");
598+
expect(res.features[0]?.properties.layer).toEqual("marinearea");
592599
});
593600
},
594601
);

package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@stadiamaps/api",
3-
"version": "7.3.0",
3+
"version": "8.0.0",
44
"description": "Stadia Maps Geospatial APIs",
55
"keywords": [
66
"stadia maps",

src/generated/apis/GeocodingApi.ts

Lines changed: 143 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
* Stadia Maps Geospatial APIs
55
* The Stadia Maps Geospatial APIs provide you with the data you need to build awesome applications.
66
*
7-
* The version of the OpenAPI document: 9.3.0
7+
* The version of the OpenAPI document: 10.0.0
88
* Contact: support@stadiamaps.com
99
*
1010
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -163,6 +163,25 @@ export interface SearchStructuredRequest {
163163
lang?: string;
164164
}
165165

166+
export interface SearchV2Request {
167+
text: string;
168+
focusPointLat?: number;
169+
focusPointLon?: number;
170+
layers?: Array<LayerId>;
171+
sources?: Array<SourceId>;
172+
boundaryGid?: string;
173+
boundaryCountry?: Array<string>;
174+
boundaryRectMinLat?: number;
175+
boundaryRectMinLon?: number;
176+
boundaryRectMaxLat?: number;
177+
boundaryRectMaxLon?: number;
178+
boundaryCircleLat?: number;
179+
boundaryCircleLon?: number;
180+
boundaryCircleRadius?: number;
181+
size?: number;
182+
lang?: string;
183+
}
184+
166185
/**
167186
*
168187
*/
@@ -1064,4 +1083,127 @@ export class GeocodingApi extends runtime.BaseAPI {
10641083
);
10651084
return await response.value();
10661085
}
1086+
1087+
/**
1088+
*/
1089+
async searchV2Raw(
1090+
requestParameters: SearchV2Request,
1091+
initOverrides?: RequestInit | runtime.InitOverrideFunction,
1092+
): Promise<runtime.ApiResponse<GeocodeResponseEnvelopePropertiesV2>> {
1093+
if (requestParameters["text"] == null) {
1094+
throw new runtime.RequiredError(
1095+
"text",
1096+
'Required parameter "text" was null or undefined when calling searchV2().',
1097+
);
1098+
}
1099+
1100+
const queryParameters: any = {};
1101+
1102+
if (requestParameters["text"] != null) {
1103+
queryParameters["text"] = requestParameters["text"];
1104+
}
1105+
1106+
if (requestParameters["focusPointLat"] != null) {
1107+
queryParameters["focus.point.lat"] = requestParameters["focusPointLat"];
1108+
}
1109+
1110+
if (requestParameters["focusPointLon"] != null) {
1111+
queryParameters["focus.point.lon"] = requestParameters["focusPointLon"];
1112+
}
1113+
1114+
if (requestParameters["layers"] != null) {
1115+
queryParameters["layers"] = requestParameters["layers"]!.join(
1116+
runtime.COLLECTION_FORMATS["csv"],
1117+
);
1118+
}
1119+
1120+
if (requestParameters["sources"] != null) {
1121+
queryParameters["sources"] = requestParameters["sources"]!.join(
1122+
runtime.COLLECTION_FORMATS["csv"],
1123+
);
1124+
}
1125+
1126+
if (requestParameters["boundaryGid"] != null) {
1127+
queryParameters["boundary.gid"] = requestParameters["boundaryGid"];
1128+
}
1129+
1130+
if (requestParameters["boundaryCountry"] != null) {
1131+
queryParameters["boundary.country"] = requestParameters[
1132+
"boundaryCountry"
1133+
]!.join(runtime.COLLECTION_FORMATS["csv"]);
1134+
}
1135+
1136+
if (requestParameters["boundaryRectMinLat"] != null) {
1137+
queryParameters["boundary.rect.min_lat"] =
1138+
requestParameters["boundaryRectMinLat"];
1139+
}
1140+
1141+
if (requestParameters["boundaryRectMinLon"] != null) {
1142+
queryParameters["boundary.rect.min_lon"] =
1143+
requestParameters["boundaryRectMinLon"];
1144+
}
1145+
1146+
if (requestParameters["boundaryRectMaxLat"] != null) {
1147+
queryParameters["boundary.rect.max_lat"] =
1148+
requestParameters["boundaryRectMaxLat"];
1149+
}
1150+
1151+
if (requestParameters["boundaryRectMaxLon"] != null) {
1152+
queryParameters["boundary.rect.max_lon"] =
1153+
requestParameters["boundaryRectMaxLon"];
1154+
}
1155+
1156+
if (requestParameters["boundaryCircleLat"] != null) {
1157+
queryParameters["boundary.circle.lat"] =
1158+
requestParameters["boundaryCircleLat"];
1159+
}
1160+
1161+
if (requestParameters["boundaryCircleLon"] != null) {
1162+
queryParameters["boundary.circle.lon"] =
1163+
requestParameters["boundaryCircleLon"];
1164+
}
1165+
1166+
if (requestParameters["boundaryCircleRadius"] != null) {
1167+
queryParameters["boundary.circle.radius"] =
1168+
requestParameters["boundaryCircleRadius"];
1169+
}
1170+
1171+
if (requestParameters["size"] != null) {
1172+
queryParameters["size"] = requestParameters["size"];
1173+
}
1174+
1175+
if (requestParameters["lang"] != null) {
1176+
queryParameters["lang"] = requestParameters["lang"];
1177+
}
1178+
1179+
const headerParameters: runtime.HTTPHeaders = {};
1180+
1181+
if (this.configuration && this.configuration.apiKey) {
1182+
queryParameters["api_key"] = await this.configuration.apiKey("api_key"); // ApiKeyAuth authentication
1183+
}
1184+
1185+
const response = await this.request(
1186+
{
1187+
path: `/geocoding/v2/search`,
1188+
method: "GET",
1189+
headers: headerParameters,
1190+
query: queryParameters,
1191+
},
1192+
initOverrides,
1193+
);
1194+
1195+
return new runtime.JSONApiResponse(response, (jsonValue) =>
1196+
GeocodeResponseEnvelopePropertiesV2FromJSON(jsonValue),
1197+
);
1198+
}
1199+
1200+
/**
1201+
*/
1202+
async searchV2(
1203+
requestParameters: SearchV2Request,
1204+
initOverrides?: RequestInit | runtime.InitOverrideFunction,
1205+
): Promise<GeocodeResponseEnvelopePropertiesV2> {
1206+
const response = await this.searchV2Raw(requestParameters, initOverrides);
1207+
return await response.value();
1208+
}
10671209
}

src/generated/apis/GeospatialApi.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
* Stadia Maps Geospatial APIs
55
* The Stadia Maps Geospatial APIs provide you with the data you need to build awesome applications.
66
*
7-
* The version of the OpenAPI document: 9.3.0
7+
* The version of the OpenAPI document: 10.0.0
88
* Contact: support@stadiamaps.com
99
*
1010
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

src/generated/apis/RoutingApi.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
* Stadia Maps Geospatial APIs
55
* The Stadia Maps Geospatial APIs provide you with the data you need to build awesome applications.
66
*
7-
* The version of the OpenAPI document: 9.3.0
7+
* The version of the OpenAPI document: 10.0.0
88
* Contact: support@stadiamaps.com
99
*
1010
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

src/generated/models/Access.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
* Stadia Maps Geospatial APIs
55
* The Stadia Maps Geospatial APIs provide you with the data you need to build awesome applications.
66
*
7-
* The version of the OpenAPI document: 9.3.0
7+
* The version of the OpenAPI document: 10.0.0
88
* Contact: support@stadiamaps.com
99
*
1010
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

src/generated/models/AddendumV2.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
* Stadia Maps Geospatial APIs
55
* The Stadia Maps Geospatial APIs provide you with the data you need to build awesome applications.
66
*
7-
* The version of the OpenAPI document: 9.3.0
7+
* The version of the OpenAPI document: 10.0.0
88
* Contact: support@stadiamaps.com
99
*
1010
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

src/generated/models/AddressComponentsV2.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
* Stadia Maps Geospatial APIs
55
* The Stadia Maps Geospatial APIs provide you with the data you need to build awesome applications.
66
*
7-
* The version of the OpenAPI document: 9.3.0
7+
* The version of the OpenAPI document: 10.0.0
88
* Contact: support@stadiamaps.com
99
*
1010
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

src/generated/models/AdminRegion.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
* Stadia Maps Geospatial APIs
55
* The Stadia Maps Geospatial APIs provide you with the data you need to build awesome applications.
66
*
7-
* The version of the OpenAPI document: 9.3.0
7+
* The version of the OpenAPI document: 10.0.0
88
* Contact: support@stadiamaps.com
99
*
1010
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

0 commit comments

Comments
 (0)