Structure Name API

Link structure IDs to names and locations

Citadel and Engineering Complex IDs are exposed by various CREST and XML APIs. Until recently CCP had not provided a mechanism that allowed third party developers to find out the name of a structure given its ID. CCP have now introduced the new ESI API that will provide the name and location for any structure that you can currently dock at. Although this is a great step forward, there are several use cases that are not covered by the new API: wallet transactions, assets and courier contracts that reference structures that you can no longer dock at. Once you lose access to a structure, CCP stop providing details about it to your tools.

This API stores details of any structure that is or was public, and combines that with structures that have been bookmarked by participants in the Structure Hunt. It also tracks whether a structure is currently accessible by the public and will in the future provide a history of changes to structure names or public access.

Query a specific structure

To use this API, simply request https://stop.hammerti.me.uk/api/citadel/STRUCTURE_ID where STRUCTURE_ID is either "all" or a structure ID that might have been returned via CCP's contracts API, the assets API, the wallet API or any others CCP add. For example, if you access https://stop.hammerti.me.uk/api/citadel/1021696460797 you will receive some JSON data such as:

	{
          "1021696460797": {
            "name": "Sarum Prime - Star Emporium", 
            "regionId": 10000043, 
            "regionName": "Domain"
            "systemId": 30003522, 
            "systemName": "Sarum Prime", 
            "firstSeen": "2016-08-14T23:33:52Z", 
            "lastSeen": "2016-08-16T13:33:28Z", 
            "typeId" : null,
            "typeName" : null,
            "public" : true,
            "location" : {
                "x" : 1.23, 
                "y" : 2.34, 
                "z" : 3.45,
            }
          }
        } 

typeId and typeName may be null for some older structure logged before the introduction of ESI, but any structure added after 10th November 2016 should have the typeId set.

public will be true if the structure was dockable by anyone at the last check, and false if the structure has a restrictive ACL or no longer exists.

location will be filled in for any citadel that has at some point been public, but will be null if the citadel has never been public.

If you request a structure ID that has not been seen, then an empty dictionary will be returned ("{}"). CCP's APIs are scraped several times an hour and if there is a particular private structure that you are interested in adding to the API, you can bookmark it yourself and contribute it via the Structure Hunt.

Swagger definition

Salacious Necrosis has contributed a swagger definition. For more info, see the forum thread.

All known structures

If you wish to download a list of all structures seen to date, use "all" instead of a structure id: https://stop.hammerti.me.uk/api/structure/all. Make sure that your client has "Accept-Encoding: gzip" set as this list is relatively large.

There is also a human-readable list of the structures that you can browse by solar system, structure type and so on.

CCP APIs known to reveal structure info

  • ESI Structure Information: shows the name, type and coordinates of any structure that you can dock at, but not the owner, or any information about structures that you cannot dock at.

  • CREST Bulk Market Orders: when you fetch an entire region of orders, ranged buy orders in a structure will reveal a structure ID, but not the name, the size of the structure or the owner.
  • CREST Individual Item Orders: When you fetch orders for one type at a time, ranged buy orders in a structure will reveal a structure ID and the name of the structure, but not the size of the structure or the owner.
  • XML KillMails: when a structure ends up on a killmail, you find out who owns the structure, the size of the structure and the x,y,z coordinates of the kill, but you don't find out the name of the structure or its ID.
  • XML Courier Contracts: courier contracts to or from structures reveal a structure ID, but not the name, the type of the structure or the owner.
  • XML Character Bookmarks or XML Corporation Bookmarks: bookmarked structures reveal a structure ID, the size of a structure and the system its in, but not the owner or the name (unless the bookmark title was not edited by the user).
  • XML Character Asset List: this fails to show any items that are in a structure, unless you set the "flat" parameter to True, in which case you don't find out about the containers an item is in!

CREST methods where structure information is missing

Limitations

This API shows structures that are public now or have been in the past, or have been bookmarked by participants in the Structure Hunt crowd-sourcing exercise. Some private structures are available through this API but not available through CCP's API, while some private structures are not available through this API at all.

We can't easily tell if a structure has been destroyed or unanchored (but the lastSeen field may be suggestive).

Buy orders seem to remain after a structure is destroyed (bug or feature? you decide!), so the lastSeen field may continue to be updated for 90 days after a structure has been destroyed or unanchored!