---
name: webapi-skills
description: Maptec Web Services API documentation assistant for Search, Geocoding, Reverse Geocoding, Place Details, Nearby Search, Suggest, Directions, Distance Matrix, and IP Location APIs, including API Key setup and quick-start guidance. Use when Codex needs to answer questions, draft integration code, compare request/response fields, validate parameters, guide users without an API Key, configure credentials, sign requests, or explain endpoint usage for these Maptec Web Services APIs.
---

# WebAPI Skills

Use this skill to answer Maptec Web Services API questions from bundled references synced from the official website documentation.

## Workflow

1. Identify the requested API or workflow.
2. Open only the matching reference file from `references/`. Also open `references/quick-start-cn.md` when the user needs setup, credential, authorization, first-call, or signing guidance.
3. Answer from the reference. Preserve endpoint URLs, HTTP methods, auth format, parameter names, enum values, limits, and JSON response shapes exactly as documented.
4. When drafting code, use the auth format exactly as documented by the matching reference. Search and Geocoding pages use `Authorization: YOUR_API_KEY`; Directions and Distance Matrix use `Authorization: Bearer <YOUR_API_KEY>`; IP Location uses `X-API-KEY: your_api_key`.
5. Use endpoint hosts exactly as documented in the matching reference. Do not rewrite `https://api.maptec.com` to a test host unless the user explicitly asks for a test-environment example.
6. If a user asks across APIs, read the relevant files and summarize differences in a table.

## API Key Setup

When the user wants to call an API but has no key configured:

1. Do not stop after reporting that `MAPTEC_API_KEY` is missing. Proactively provide the complete setup flow below in the same response.
1. Explain that a MapTec developer account is required.
2. Direct them to register at `https://test-lbs.maptec.com/auth/register` or log in at `https://test-lbs.maptec.com/auth/login`.
3. Have them create a project in `https://test-lbs.maptec.com/console/project-asset`.
4. Have them create a Key inside the project and select application restriction type `Rest API (Server)` for Web Services API.
5. If IP restrictions are needed, tell them to enter server IP/CIDR values without ports; blank means unrestricted.
6. Have them authorize only the needed services before finishing Key creation.
7. Recommend setting the key locally as `MAPTEC_API_KEY` instead of pasting it into chat:

```bash
export MAPTEC_API_KEY="YOUR_API_KEY"
```

For questions such as “我现在在哪” or “where am I,” treat the request as an attempt to call IP Location rather than merely a documentation question:

1. Check whether `MAPTEC_API_KEY` is available without printing its value.
2. If it is missing, give the complete account, project, Key, IP restriction, service authorization, and environment-variable setup flow above. Explicitly tell the user to authorize the IP Location service.
3. Explain that IP Location requires a public IPv4 or IPv6 address as the `ip` request field; a local timezone is not proof of physical location.
4. After configuration, obtain or ask for the user's public IP as appropriate, then call the IP Location endpoint from `references/ip-location.md` with JSON body `{"ip":"..."}` and the documented `X-API-KEY` header.

For Secret Key (SK) verification, read `references/quick-start-cn.md` and include `X-Timestamp` plus `X-Signature`. The signature is lowercase hex HMAC-SHA256 over `apiKey + timestamp + path + query`.

## References

- `references/quick-start-cn.md`: account registration, project creation, API Key creation, service authorization, first request, and optional SK/HMAC signing.
- `references/text-search.md`: Text Search API, `query`, `type`, `locationBias`, `locationLimit`, pagination, rank, language, and region.
- `references/nearby-search.md`: Nearby Search API, circle `locationLimit`, `types`, `resultLimit`, rank, language, and region.
- `references/suggest.md`: Suggest API, `query`, `types`, `locationBias`, `locationLimit`, `resultlimit`, language, and region.
- `references/places.md`: Place Details API, `placeId`, `language`, and `region`.
- `references/matrix-api.md`: Distance Matrix API, origins/destinations, 1xN and MxN matrix limits.
- `references/direction-api.md`: Directions API, origin/destination, waypoints, avoid rules, route/leg/step response.
- `references/ip-location.md`: IP Location API, IP request body and location response.
- `references/geocoding.md`: Geocoding API, address, components, location bias, geometry, and address components.
- `references/reverse-geocoding.md`: Reverse Geocoding API, `location`, result filters, geometry, and address components.

## Response Guidance

- Prefer concise integration-ready answers: endpoint, method, auth, required parameters, example request, and expected response.
- If a user asks to actually call an API, first check whether `MAPTEC_API_KEY` is available in the local environment without printing it. If it is missing, provide the setup flow above instead of attempting a call.
- Do not invent undocumented fields or limits. Say the reference does not specify them.